M-CMP IAM Manager docs

M-CMP IAM Manager

This repository provides a multi-cloud IAM management framework as a subsystem of the M-CMP platform for deploying and managing multi-cloud infrastructure.

Table of Contents

• Overview
• Key Features
• System Architecture
• Quick Start
• Installation and Configuration
• API Documentation
• Contributing
• License

Overview

M-CMP IAM Manager provides an integrated authorization and access control framework for multi-cloud environments. It offers platform account/role management, integrated management of cloud account/access control information, and workspace management functionality to support security policy decision-making, establishment, and enforcement for existing multi-cloud services.

Key Characteristics

• Multi-cloud Support: Integrated management of various CSPs including AWS, GCP, Alibaba Cloud, Tencent Cloud, NCP, NHN, KT Cloud, and OpenStack
• RBAC-based Access Control: Role-based granular permission management
• Centralized Management: Single platform control for all cloud resource access
• Temporary Credentials: JWT-based secure temporary access token issuance

Key Features

🏢 Enterprise Multi-cloud Environment Management

• Multi-CSP Integration: Unified management of IAM across multiple cloud service providers including AWS, GCP, Alibaba Cloud, Tencent Cloud, NCP, NHN, KT Cloud, and OpenStack
• Centralized Permission Control: Manage access permissions for all cloud resources from a single platform
• RBAC (Role-based Access Control): Granular permission management based on user roles
• Temporary Credentials: JWT-based secure temporary access token issuance

System Architecture

Internet
    |
    v
[Nginx Reverse Proxy] (Port 80/443)
    |
    +---> [IAM Manager] (Port 5000)
    |
    +---> [Keycloak] (Port 8080)
    |
    +---> [PostgreSQL] (Port 5432)

Components

• Nginx: Reverse proxy, SSL termination, static file serving
• IAM Manager: Main application (Echo Framework)
• Keycloak: Authentication and authorization management
• PostgreSQL: Database
• Certbot: Automatic SSL certificate issuance/renewal

Quick Start

mc-admin-cli contains mc-iam-manager.

Prerequisites

• Operating System: Ubuntu 22.04 (tested)
• Network: External access capability (HTTPS-443, HTTP-80, SSH-ANY)
• Docker: Docker 24+ and Docker Compose v2
• Database: PostgreSQL
• Domain: Domain for SSL certificate issuance (production environment)
• Email: Email address for SSL certificate issuance

Installation Steps

Step 1: Clone Source

git clone https://github.com/m-cmp/mc-iam-manager <YourFolderName>
cd <YourFolderName>

Step 2: Environment Configuration

# Copy environment configuration file
cp .env_sample .env

# Edit environment variables
nano .env

Key Configuration Items:

• MC_IAM_MANAGER_EXTERNAL_DOMAIN: Domain name (e.g., mciam.m-cmp.org)
• MC_IAM_MANAGER_CERT_EMAIL: Email for SSL certificate issuance
• MC_IAM_MANAGER_PORT: Application port (default: 5000)
• MC_IAM_MANAGER_KEYCLOAK_ADMIN: Keycloak administrator account
• MC_IAM_MANAGER_KEYCLOAK_ADMIN_PASSWORD: Keycloak administrator password

Step 3: Certificate Configuration

Development Environment (Self-signed Certificate):

• Self-signed Certificate Issuance Guide

Production Environment (CA Certificate):

• CA Certificate Issuance Guide

Step 4: System Deployment

Full System Deployment (Recommended):

sudo docker compose -f docker-compose.yaml up -d

With SSL Certificate (Production):

sudo docker compose -f docker-compose.yaml -f docker-compose.cert.yaml up -d

Direct Source Code Execution:

cd ./src
go run main.go

Docker Deployment with Local Build

The mc-iam-manager service is configured to use the local Dockerfile.mciammanager for building the container image.

Build Configuration

In docker-compose.yaml, the service is configured as:

mc-iam-manager:
  build:
    context: .
    dockerfile: Dockerfile.mciammanager
  image: cloudbaristaorg/mc-iam-manager:edge

Deployment Options

1. Build and Run mc-iam-manager:

# Build from local Dockerfile and start
docker-compose up --build mc-iam-manager

# Run in background
docker-compose up --build -d mc-iam-manager

2. Run All Services:

# Build and start all services
docker-compose up --build -d

3. Rebuild from Scratch:

# Force rebuild without cache
docker-compose build --no-cache mc-iam-manager
docker-compose up -d mc-iam-manager

4. Run with Dependencies Only:

# Start mc-iam-manager with required services
docker-compose up -d mc-iam-manager-db mc-iam-manager-kc mc-iam-manager

Service Dependencies

The mc-iam-manager service requires:

• mc-iam-manager-db (PostgreSQL database)
• mc-iam-manager-kc (Keycloak for authentication)

These dependencies are automatically started when you run mc-iam-manager.

Image Management

# Pull latest images (if using pre-built images)
docker-compose pull

# List Docker images
docker images | grep mc-iam-manager

# Remove old images
docker rmi cloudbaristaorg/mc-iam-manager:edge

Step 5: Operation Verification

curl https://<your domain or localhost>:<port>/readyz

Installation and Configuration

Initial Setup

1. Authentication Configuration

Production Environment (Domain and CA Certificate):

./asset/setup/0_preset_prod.sh

Development Environment (localhost and Self-signed Certificate):

./asset/setup/0_preset_dev.sh

2. Basic Configuration

Automatic Setup (Recommended):

./asset/setup/1_setup_auto.sh

Manual Setup:

./asset/setup/1_setup_manual.sh

Configuration Steps

1. Platform and Administrator Initialization

   • Create Keycloak Realm
   • Create Keycloak Client
   • Create and register default roles
   • Create default workspace
   • Register menus and role mapping
   • Create platform administrator user

2. API Resource Configuration

   • Initialize API resource data
   • Configure cloud resource data
   • Map API-cloud resources

3. CSP Role Configuration

   • Initialize CSP roles
   • Map master roles-CSP roles

CSP IDP Configuration (Production Environment)

1. CSP Console Configuration

   • Add IDP configuration in IAM menu
   • Add IAM roles (prefix: mciam_)
   • Configure role permissions
   • Configure Trust Relation settings

2. MC-IAM-Manager Configuration

   • Add CSP roles
   • Configure role mapping

Operations Management

Log Monitoring

# Check specific service logs
sudo docker compose logs [service-name]

# Real-time log monitoring
sudo docker compose logs -f [service-name]

Backup

# PostgreSQL data backup
sudo docker exec <mc-iam-manager-db service name> pg_dump -U <db user> <db name> > backup.sql

# Keycloak data backup
sudo tar -czf keycloak-backup.tar.gz container-volume/keycloak/

Update

# Update images
sudo docker compose -f docker-compose.yaml pull
sudo docker compose -f docker-compose.yaml up -d

API Documentation

Generate Swagger Documentation

cd ./src
swag init --output ./docs

Access API Documentation

• Online Documentation: https://m-cmp.github.io/mc-iam-manager/
• Local Documentation: http://localhost:<port>/swagger/index.html

User Management

Basic User Addition

1. Platform Administrator Login

   POST /api/auth/login
   {
     "id": "<MCIAMMANAGER_PLATFORMADMIN_ID>",
     "password": "<MCIAMMANAGER_PLATFORMADMIN_PASSWORD>"
   }

2. Add Users

   • Create user accounts
   • Map users to roles
   • Share workspaces (optional)

Role Management

Default Roles:

• admin: Administrator permissions
• operator: Operator permissions
• viewer: View permissions
• billadmin: Cost management permissions
• billviewer: Cost viewing permissions

Troubleshooting

mc-iam-manager Stays Unhealthy After Install

If docker compose ps shows mc-iam-manager as unhealthy and docker logs mc-iam-manager-post-initial ends with ERROR: 1_setup_auto.sh failed, the post-init container ran before mc-iam-manager finished its first boot (cold-start timing race).

Recovery:

# 1. Confirm all prerequisites are healthy
docker compose ps

# 2. Remove the exited post-init container, then re-run it
docker rm mc-iam-manager-post-initial 2>/dev/null
docker compose up -d mc-iam-manager-post-initial
docker logs -f mc-iam-manager-post-initial
# Each of the 8 setup steps should finish with ✓

# 3. Verify
curl -s http://localhost:${MC_IAM_MANAGER_PORT}/readyz | jq .
# Expected: "status": "healthy"

The post-init container is idempotent — it is safe to re-run.

Directory Permission Error When Running 0_preset_dev.sh

If 0_preset_dev.sh fails with Cannot create ... / is not writable, root-owned files from a previous Docker run are blocking access. Clean them up and retry:

sudo rm -rf container-volume/mc-iam-manager/postgres container-volume/mc-iam-manager/keycloak
./conf/mc-iam-manager/0_preset_dev.sh

---

Contributing

• Report Issues: GitHub Issues
• Discussions: GitHub Discussions
• Suggest Ideas: GitHub Issues

License

This project is distributed under the Apache 2.0 License.