About Deployment Configuration

Cloudentity comes with possibilities to export and import the configuration for your Cloudentity deployment. For this, you can use Cloudentity’s built-in command line interface (CLI). Also, Cloudentity export/import APIs are available within all deployment types and can be used, for example, to automate configuration.

Export/Import APIs

Cloudentity feature four endpoints to export and import tenant configuration.

Tenant-specific operations are available for both on-premise and SaaS Cloudentity versions.

Global operations are available for on-premise Cloudentity versions since the system tenant is available for on-premise deployments only:

• Export configuration to globally export your complete Cloudentity deployment configuration for all tenants.

• Import configuration to globally export your entire Cloudentity deployment configuration for all tenants.

Configuration File Format

All configuration import/export endpoints return/accept JSON with the configuration.

Exporting/Importing Global Tenants Configuration With API

The Cloudentity deployment version supports the REST API to export and import the configuration for all tenants within your deployment at once. This operation requires access to your System tenant.

The Export response contains a JSON with all tenants and their configurations.

Export Global Configuration

1. Obtain an access token.

   • Use the client credentials grant to obtain an access token. The client ID of your System tenant application is system. The matching client secret is already set for this client application.

   • Subscribe your client application to the manage_configuration scope to call the token endpoint.

2. Call the export configuration endpoint.

   Export Global Configuration Request Sample

   curl -o {FileName.json} --location --request GET "https://$TENANT_ID/api/system/configuration" \
   -H "Authorization: Bearer $ACCESS_TOKEN"
   

   -o {FileName.json} saves the configuration in your current directory. You can skip this flag and copy the configuration from the response body. Then, save it as JSON manually.

Your configuration is returned as JSON in the response. The response includes configuration for all workspaces within all tenants and doesn’t include dynamic and non-configuration data. You can change this with optional request parameters.

Import Global Configuration

1. Obtain an access token.

   • Use the client credentials grant to obtain an access token. The client ID of your System tenant application is system. It also features the matching client secret.

   • Specify the manage_configuration scope when calling the token endpoint.

2. Call the import configuration endpoint.

   Import Global Configuration Request Sample

   curl --location --request PUT "https://$TENANT_ID/api/system/configuration" \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   -d @{FileName.json} // optional
   

   Skip -d {FileName.json} when you pass the configuration within the request body.

As a result, your configuration is imported and available within your Cloudentity deployment.

Export/Import CLI

On-premise users can employ Cloudentity’s built-in CLI to export and import their tenant configuration. Still, the point is to call the export/import APIs, so the capabilities are the same: export and import configuration per a specific tenant or all tenants available within a deployment.

You do not need to get access tokens; the CLI does it for you. A direct benefit of using the CLI is that it makes integrating with DevSecOps pipelines much easier since you can execute import in a satellite environment such as a Kubernetes cluster.

The export/import APIs are protected by the System tenant’s credentials. For this reason, you provide the client identifier, client secret, and issuer url arguments to CLI commands. The Prerequisites section describes how to prepare these arguments.

The export/import CLI, among others, accepts the following arguments:

• --client-id: The identifier of the client application to be authenticated.

• --client-secret: The secret of the client application to be authenticated.

• --issuer-url: The issuer URL for the client application that gets authenticated. You can find your tenant’s issuer URL in your workspace settings.

Issuer URL, Tenant ID, and Authorization Server ID

When using the import CLI, the issuer URL argument is used for client authentication and defining whether the operation is global or tenant-specific.

In some cases, Cloudentity cannot retrieve tenant and authorization server identifiers from the issuer URL, for example, when vanity domains are used to expose Cloudentity on a custom domain. To handle this, the CLI accepts the --tenant-id and --server-id arguments. You can pass them with the import command to enable the client application authentication.

Global and Tenant-Specific Operations

Cloudentity CLI can distinguish global export/import and tenant-specific by the --issuer-url argument.

The operation is considered tenant-specific when the issuer URL is a URL of a tenant, different from the system tenant. Then, the operation is applied to the configuration of the given tenant.

When the issuer URL is a URL of a system tenant, the operation is considered global. Export and import are applied to all tenants within the deployment.

Still, you can export and import a specific tenant configuration performing the global operation. For this, pass the --tenant $TENANT_ID argument, where $TENANT_ID is the identifier of the required tenant. As a result, you export/import the configuration for the given tenant. At the same time, the issuer URL is set to your system tenant value.

Prerequisites

1. Your Cloudentity has a valid root certificate.

2. The integration_endpoints feature flag is ON for the required deployment.

3. The client application is created within the appropriate location.

   • Global operation: within the System tenant.

   • Tenant-specific operation: within the System workspace of the required tenant.

4. The client application is set up as follows:

   • Token Endpoint Authentication method is client_secret_basic.

     This method is used when the client authenticates itself to Cloudentity before making a call to the export/import APIs.

   • The manage_configuration scope is enabled.

     Cloudentity CLI requires this scope since both export and import are part of the configuration management.

Export/Import With CLI

1. In the terminal, navigate to the directory where your Cloudentity deployment binary files are stored. Look for the acp binary file.

   Cloudentity on K8s

   For Cloudentity deployment on Kubernetes: attach a bash shell to the pod where your Cloudentity is deployed. For this, run:

   kubectl exec -it {POD} -n {NAMESPACE} sh.

2. To export configuration, run the following:

   ./acp export --client-id $CLIENT_ID --client-secret $CLIENT_SECRET --issuer-url $ISSUER_URL
   

   • Specify the format for the configuration you receive. Add --format {yaml/json} to your export command.

   • You can pass a certificate from your Cloudentity configuration. Add --config path/to/your/config to your export command.

3. To import the configuration, run the following:

   ./acp import --client-id $CLIENT_ID --client-secret $CLIENT_SECRET --issuer-url $ISSUER_URL --input {FileName.format}
   

   • {FileName.format} is the name of your configuration file. Paste the whole path when running the import command in any other directory than you’re currently in.

   • You can pass a certificate from your Cloudentity configuration. For this, add --config path/to/your/config to your import command.

CLI Help

To get help with the Cloudentity CLI syntax, use -h. It triggers the CLI reference guide.

For example, check the export operation: run acp export -h in your terminal.

Insert Mode

The import endpoints support the mode query parameter. This parameter is optional; it defines what happens in the case of import conflicts. For example, when importing a configuration between two tenants, and both have client applications with identical IDs.

Cloudentity can handle this conflict as follows:

• mode=ignore: Ignore the incoming configuration from the source. Applies to the conflicting changes.

• mode=fail: Stop import processing and return an error.

• mode=update: Overwrite the target with the incoming configuration from the source. Applies to the conflicting changes.

By default, mode = ignore.

Export Response Options

You can adjust the response content you receive upon calling the export endpoint.

• Get an individual workspace configuration only:

  Pass the workspace_id=$WORKSPACE_ID query parameter with your request. $WORKSPACE_ID is the ID of the required workspace.

• Include dynamic and non-configuration data to the configuration:

  Set the with_data query parameter to true when calling the export configuration endpoint.