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
-
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.
-
-
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
-
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.
-
-
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
-
Your Cloudentity has a valid root certificate.
-
The
integration_endpoints
feature flag is ON for the required deployment. -
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.
-
-
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
-
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
. -
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.
-
-
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 totrue
when calling the export configuration endpoint.