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

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.

1. 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

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.

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

2. Extract the release.

3. 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" $*
   

4. Run the following command to view the available commands:

   CLI Command

   iamctl -h
   

Running the tool

1. Create a new folder and navigate to it from your terminal.

2. Run the following command to create the configuration files needed.

   CLI Command

   iamctl setupCLI
   

3. 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.

4. 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://api.asgardeo.io",
       "CLIENT_ID" : "bsjhjlb64crOL58bKV3UQmwA9QQa",
       "CLIENT_SECRET" : "TC45TBkLaZ6kFxqZuSmhOgelSG2ZBvFYKFlUFmfhKlYa",
       "TENANT_DOMAIN" : "bifrostdev",
       "SERVER_VERSION" : ""
   }
   

5. 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

Register tool management application and share with child organizations

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.

1. Register a Standard-Based Application in the root organization.
2. Share the application with the relevant child organization (e.g., wso2.com).
3. Allow following grant types in the newly created Standard-Based Application:
   • Client Credentials
   • Organization Switch
4. 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://api.asgardeo.io",
    "CLIENT_ID" : "bsjhjlb64crOL58bKV3UQmwA9QQa",
    "CLIENT_SECRET" : "TC45TBkLaZ6kFxqZuSmhOgelSG2ZBvFYKFlUFmfhKlYa",
    "TENANT_DOMAIN" : "bifrostdev",
    "SERVER_VERSION" : "",
    "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.