Promote configurations across environments¶

This guide outlines the recommended workflow for promoting resource configurations seamlessly between environments. By leveraging the IAM-CTL tool, you can efficiently manage configurations, automate deployments, and ensure consistency across your environments.

Why use IAM-CTL tool?¶

The IAM-CTL tool is a command-line utility that can simplify the management of configurations.

Bulk Configuration Management: Handle large-scale configurations in your target environment effortlessly.
Environment Promotion: Promote resources across multiple environments with ease.
Backup and Restore: Act as a backup solution for environment configurations.
CI/CD Integration: Automate deployment processes and resource propagation using CI/CD pipelines. To integrate IAM-CTL with GitHub workflows, refer to the sample workflow guide.

Supported resource types¶

IAM-CTL provides support for propagating the following resource types among root organizations:

Applications
Identity Providers
Claims
User Stores
API Resources
OIDC Scopes
Roles
Email Templates
Governance Connectors
Validation Rules
Organizations
Branding
SMS Templates
Actions

Getting started¶

Before using IAM-CTL, you need to register Machine-to-Machine (M2M) applications in your target environments. If you are propagating resources between root organizations, you need to create M2M apps in root organizations. These applications will be used by IAM-CTL to authenticate and perform operations on your behalf.

Register tool management application¶

Follow the steps below to register an M2M application.

Register an M2M application with the following API authorization.

Management --> Application Management API	Create Application, Update Application, Delete Application, View Application, Update authorized business APIs of an Application, Update authorized internal APIs of an Application, View application client secret, Regenerate Application Secret
Management --> Application Authentication Script Management API	Update Application Authentication Script
Management --> Claim Management API	Create Claim, Update Claim, Delete Claim, View Claim
Management --> Identity Provider Management API	Create Identity Provider, Update Identity Provider, Delete Identity Provider, View Identity Provider
Management --> Userstore Management API	Create Userstore, Update Userstore, Delete Userstore, View Userstore
Management --> API Resource Management API	Create API Resource, Update API Resource, Delete API Resource, View API Resource
Management --> OIDC Scope Management API	Create OIDC Scopes, Update OIDC Scopes, Delete OIDC Scopes, View OIDC Scopes
Management --> SCIM2 Roles V1/V2 API	Create Role, Update Role, Delete Role, View Role, Update Permissions of Role
Management --> Identity Governance Management API	View Identity Governance, Update Identity Governance
Management --> Validation Rules API	Update Validation Rule
Management --> Organization Management API	Create Organizations, Update Organizations, Delete Organizations, View Organizations
Management --> Branding Preference Management API	Update Branding Preference
Management --> Notification Template Management API	Create Notification Template, Update Notification Template, Delete Notification Template, View Notification Template
Management --> Action Management API	Create Action, Update Action, Delete Action, View Action

Take note of the Client ID and Client Secret of the M2M application you created.

Setting up IAM-CTL¶

Follow the steps below to learn how you can configure IAM-CTL.

Download the latest release from releases based on your Operating System.
Extract the release.

Open a terminal and create an alias (depending on your platform):

Linux/macOSWindows

alias iamctl="<IAM-CTL-PATH>/bin/iamctl"

doskey iamctl="<IAM-CTL-PATH>\bin\iamctl.exe" $*

Run the following command to view the available commands:
CLI Command
iamctl -h

Running the tool¶

Create a new folder and navigate to it from your terminal.
Run the following command to create the configuration files needed.
CLI Command
iamctl setupCLI
A new folder named configs will be created with an env folder inside it. The env folder will contain three configuration files, serverConfig.json, toolConfig.json, and keywordConfig.json.

Note

If you have multiple environments, get a copy of the env folder and rename it according to the environments you have.

Open the serverConfig.json file and provide the client ID and client secret of the application you created earlier.

To propagate resources between root organizations, provide the details of the M2M application created in the root organization and the organization details.

serverConfig.jsonExample

{
    "SERVER_URL" : "{server_url}",
    "CLIENT_ID" : "{client_id}",
    "CLIENT_SECRET" : "{client_secret}",
    "TENANT_DOMAIN" : "{tenant_domain}",
    "SERVER_VERSION" : "{server_version}"
}

{
    "SERVER_URL" : "https://localhost:9443",
    "CLIENT_ID" : "bsjhjlb64crOL58bKV3UQmwA9QQa",
    "CLIENT_SECRET" : "TC45TBkLaZ6kFxqZuSmhOgelSG2ZBvFYKFlUFmfhKlYa",
    "TENANT_DOMAIN" : "carbon.super",
    "SERVER_VERSION" : "7.1"
}

Run the following commands to export and import configurations.

a. Export
CLI Command
iamctl exportAll -c ./configs/env
b. Import
CLI Command
iamctl importAll -c ./configs/env

Propagate resources between child organizations¶

IAM-CTL enables you to propagate configurations and resources across child organizations in an organization hierarchy.

Supported resource types:

Applications
Identity Providers
User Stores

If the target environment is a child organization, ensure that a Standard-Based Application is created within the root organization and shared with that specific child organization.

Register a Standard-Based Application in the root organization.
Share the application with the relevant child organization (e.g., wso2.com).
Allow following grant types in the newly created Standard-Based Application:
- Client Credentials
- Organization Switch
Grant the following API authorizations under Organization APIs.

Organization --> Application Management API	Create Application, Update Application, Delete Application, View Application, Update authorized business APIs of an Application, Update authorized internal APIs of an Application, View application client secret, Regenerate Application Secret
Organization --> Application Authentication Script Management API	Update Application Authentication Script
Organization --> Identity Provider Management API	Create Identity Provider, Update Identity Provider, Delete Identity Provider, View Identity Provider
Organization --> Userstore Management API	Create Userstore, Update Userstore, Delete Userstore, View Userstore

Take note of the Client ID and Client Secret of the application you created.

Update the tool¶

Open the serverConfig.json file and provide the details of the application shared with the child organization and the child organization details, before running the tool.

serverConfig.jsonExample

{
    "SERVER_URL" : "{server_url}",
    "CLIENT_ID" : "{client_id}",
    "CLIENT_SECRET" : "{client_secret}",
    "TENANT_DOMAIN" : "{tenant_domain}",
    "SERVER_VERSION" : "{server_version}",
    "ORGANIZATION": "{organization_id}"
}

{
    "SERVER_URL" : "https://localhost:9443",
    "CLIENT_ID" : "bsjhjlb64crOL58bKV3UQmwA9QQa",
    "CLIENT_SECRET" : "TC45TBkLaZ6kFxqZuSmhOgelSG2ZBvFYKFlUFmfhKlYa",
    "TENANT_DOMAIN" : "carbon.super",
    "SERVER_VERSION" : "7.1",
    "ORGANIZATION": "b833d7de-264c-4c4e-8d52-61f9c57e84ca"
}

Customization options¶

IAM-CTL provides the following advanced customization options to handle environment-specific needs and streamline configuration management:

Keyword mapping¶

When managing multiple environments, resource configuration files often contain environment-specific variables. IAM-CTL supports dynamic keyword replacement to handle these variables during import or export. Keyword mapping can also be defined for specific resources within that environment.

For more details, refer to the environment-specific variables guide.

Partial propagation¶

IAM-CTL supports partial propagation of resources using the below properties.

EXCLUDE: Exclude specific resource types or a set of individual resources during import or export.
INCLUDE_ONLY: Include only specific resource types or a set of individual resources during import or export.

Resource deletion¶

By default, IAM-CTL does not delete any resources during import. It can be configured to either replace all existing resources with the imported resources or merge the imported resources with the existing ones using the ALLOW_DELETE property.

Secret handling¶

IAM-CTL provides options to manage sensitive data securely. By default, secrets fields are masked. The EXCLUDE_SECRETS property can be used to override this behavior and include the secrets in the exported resources.

Learn more about these configurations in the tool configurations documentation.

Logging¶

IAM-CTL uses a unified logging system that provides structured, filterable log output with resource context and an end-of-run summary after every export or import operation.

Log configuration¶

Add a LOGS block to your toolConfig.json to configure logging behavior:

toolConfig.json

{
    "LOGS": {
        "LOG_LEVEL": "INFO",
        "LOG_REQUEST_PAYLOADS": false
    }
}

Property	Values	Default	Description
`LOG_LEVEL`	`DEBUG`, `INFO`, `WARN`, `ERROR`	`INFO`	Minimum log level to print. Messages below this level are suppressed.
`LOG_REQUEST_PAYLOADS`	`true`, `false`	`false`	When set to `true`, HTTP request bodies are logged at `DEBUG` level for POST and PUT requests.

Sensitive data in request payloads

Request bodies may contain sensitive credentials (client secrets, passwords, access tokens). Enabling LOG_REQUEST_PAYLOADS will write these values to your log output. Only enable this option in secure, non-production environments, and ensure log files are adequately protected.

Resource-specific notes¶

Note the following resource-type-specific behavior when using IAM-CTL.

Note

IAM-CTL treats users and groups as dynamic configurations that are not portable across environments. When a resource contains embedded user or group data, IAM-CTL strips that data during export. As a result, import removes this data from the affected resource in the target environment. For resources that contain dynamic data, use IAM-CTL for initial resource creation only. Add the dynamic configurations manually, then exclude the resource in future imports using EXCLUDE to preserve the data.

Roles¶

Users and groups assigned to roles are not exported or imported by IAM-CTL.

Claims¶

Claim dialect names may contain characters that are not valid in file names (e.g., http://wso2.org/oidc/claim). IAM-CTL uses an escaped version of the dialect name as the file name (e.g., http_wso2_org_oidc_claim). When referencing a claim dialect in tool configurations such as EXCLUDE or keyword mappings, use the exact claim dialect name, not the escaped file name.

User stores¶

When propagating user stores, do not exclude the local claim dialect (http://wso2.org/claims). Excluding it will prevent new claim attribute mappings of user stores from being propagated.

Applications¶

When propagating applications, do not exclude roles. Excluding roles will prevent new application roles from being propagated.

Governance connectors¶

Group-based password expiry rules of the password expiry connector are not exported by IAM-CTL. As a result, these rules will be removed from the connector on import, when ALLOW_DELETE is enabled.

Organizations¶

When referencing organizations in tool configurations such as EXCLUDE or keyword mappings, use the organization handle as the resource name.

When IAM-CTL creates organizations using the management application credentials, no user is assigned as the creator. As a result, no user has access to the newly created organization after creation. You can manually assign an organization admin after IAM-CTL creates the organization.

To assign a creator at import time, configure CREATOR_ID and CREATOR_USERNAME under ORGANIZATIONS in toolConfig.json.

toolConfig.json

{
    "ORGANIZATIONS": {
        "CREATOR_ID": "<user-id>",
        "CREATOR_USERNAME": "<username>"
    }
}

When both values are set, IAM-CTL assigns the specified user as the organization creator on import. IAM-CTL strips these attributes on export and does not store them in the exported files, as they are environment-specific and not portable.

Branding¶

Branding contains two sub-resource types: Branding Preferences and Custom Texts. When referencing branding in tool configurations such as EXCLUDE or keyword mappings, use the sub-resource type names as shown below.

toolConfig.json

{
    "EXCLUDE": ["BrandingPreferences"],
    "CUSTOM_TEXTS": {
        "EXCLUDE": ["screen1"]
    }
}

Promote configurations across environments¶

Why use IAM-CTL tool?¶

Supported resource types¶

Getting started¶

Register tool management application¶

Setting up IAM-CTL¶

Running the tool¶

Propagate resources between child organizations¶

Register tool management application and share with child organizations¶

Update the tool¶

Customization options¶

Keyword mapping¶

Partial propagation¶

Resource deletion¶

Secret handling¶

Logging¶

Log configuration¶

Resource-specific notes¶

Roles¶

Claims¶

User stores¶

Applications¶

Governance connectors¶

Organizations¶

Branding¶