

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:

Applications
Identity Providers
Claims
User Stores
Roles
OIDC Scopes
Challenge Questions
Email Templates
Script Libraries
Certificates
Governance Connectors

Note

Management of the Resident Identity Provider and Kerberos, OpenID inbound authentication configurations of service providers is not supported with IAM-CTL.

Getting started¶

Before using IAM-CTL, you must register an OAuth application in your target environments. These applications will be used by IAM-CTL to authenticate and perform operations on your behalf.

Register tool management application¶

Follow these steps to register your application:

Log in to the Management Console.
Go to Main > Identity > Service Providers and click Add.
Enter a Service Provider Name (e.g., IAM-CTL-App) and click Register.
Expand Inbound Authentication Configuration > OAuth/OpenID Connect Configuration and click Configure.
Ensure only Client Credentials is selected under Allowed Grant Types.
Click Add.

Take note of the OAuth Client Key (Client ID) and OAuth Client Secret that are generated.

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/macOS

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

Windows

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

Run the following command to view the available commands:
```
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.
```
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 and the tenant details.

serverConfig.json

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

Example

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

Run the following commands to export and import configurations.

Export
```
iamctl exportAll -c ./configs/env
```
Import
```
iamctl importAll -c ./configs/env
```

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.

Top