How-tos

Exporting and Importing Cloudentity Tenants Configuration

Learn how to export and import Cloudentity tenant's configuration using API and built-in Cloudentity command line interface (CLI), which is available for on-premise deployments. You can move tenants' configuration between your different Cloudentity deployments, or use it for configuration automation. You can also export and import the entire Cloudentity configuration for all tenants.

About Tenant Configuration

Cloudentity comes with a few possibilities on how you can export or import your tenants' configuration. Cloudentity export/import APIs are available for all deployment types and can be used, for example, for configuration automation. Cloudentity’s built-in command line interface (CLI) can be used by on-premise deployments of Cloudentity.

Import/Export APIs

With Cloudentity system API you can export and import your tenants' configuration. There are four dedicated endpoints that allow you to do that:

Note

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

Import/Export CLI

The Cloudentity’s built-in import/export CLI allows the on-premise users to import and export a tenant’s configuration. It works by calling the import/export APIs so it has the same capabilities: you can either import or export configuration of a specific tenant or from all tenant’s available within your deployment. You do not need to get access tokens, the CLI does that for you. A straightforward benefit of using the CLI is that it makes the integration with DevSecOps pipelines much easier as the import can be executed in a satelite environment like, for example, a Kubernetes cluster.

To learn how to use the CLI, see the Configuration management using CLI section.

Exporting/Importing Tenant’s Configuration Using API

With Cloudentity system API, you can export and import a specific tenant’s configuration. There are many reasons to do it. It can be used for configuration automation or, for example, you can move tenant’s configuration between different Cloudentity deployments. A company that delivers its services to financial institutions and uses Cloudentity to protect their APIs, may want to import an Open-Banking-directive-compliant tenant’s configuration from one of their deployments to the deployment of their customers.

Prerequisites

  1. You have access to the system workspace.

  2. A client application that allows you to make requests to the token endpoint is created in the system workspace.

    Note

    To learn how to set up such application, see the Getting started with Cloudentity REST API guide, section Preconfigure your workspace.

    Preconfigure your workspace describes how to create the client application that you need, but for the Admin workspace and admin APIs. What you need to do, is to create similar application in the System workspace and assign the manage_configuration scope to it.

Export Configuration

  1. Call the OAuth 2.0 token endpoint to get an access token.

    Remember

    Your access token must have the manage_configuration scope added if there are any additional scopes assigned to the token.

    Even if there are no scopes defined in your request, it is good security practice to limit the scope assigned to the token.

    Learn More

    If you need help with getting the token, see the Getting started with Cloudentity REST API guide, section Call the token endpoint.

  2. Call the export tenant configuration endpoint

    Request Example

    curl -o configuration.json --location --request GET 'https://{tid}.authz.cloudentity.io/api/system/{tid}/configuration' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}'
    

    The {tid} path parameter is your tenant identifier.

    Replace the {ACCESS_TOKEN} variable with the access token that you got in the first step.

Result

Your tenant configuration is returned as JSON in the request response body. You can copy and save it or use the -o configuration.json curl request parameter (as provided in the request example) to save the response body to a JSON file.

The file is saved in the current location you are at when sending the curl request.

Import Configuration

  1. Call the OAuth 2.0 token endpoint to get an access token.

    Remember

    Your access token must have the manage_configuration scope added if there are any additional scopes assigned to the token.

    Even if there are no scopes defined in your request, it is good security practice to limit the scope assigned to the token.

    Learn More

    If you need help with getting the token, see the Getting started with Cloudentity REST API guide, section Call the token endpoint.

  2. Call the import tenant configuration endpoint.

    Request Example

    curl --location --request PUT 'https://{tid}.authz.cloudentity.io/api/system/{tid}/configuration' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -d @configuration.json
    

    The {tid} path parameter is your tenant identifier.

    Replace the {ACCESS_TOKEN} variable with the access token that you got in the first step.

    You can either paste your JSON tenant configuration to your request or point to the file that contains the configuration using the -d @YourFileName.json parameter. If you are using a file to provide the request body content, you must make the request from the location the file is placed in or provide a whole path to your file, for example -d @path/to/your/file/YourFile.json.

    Tip

    You can see that in the example request, the request body parameter points to the configuration file that was saved after the request to the export tenant configuration endpoint.

    Before the import, you can, of course, modify the content of your configuration file and adjust it to your needs.

Result

Your tenant configuration is imported and available within Cloudentity.

Exporting/Importing Global Tenants Configuration

Customers that use the on-premise version of the Cloudentity deployment can use the global tenants' configuration export/import Cloudentity REST APIs. The requirement to have the on-premise deployment comes from the fact, that you need to be able to access the system tenant of your deployment.

Using the Export configuration API you can export the configuration of all tenants available for your deployment. The response from this endpoint contains a JSON with all tenants and their configuration.

Export Global Configuration

  1. Call the OAuth 2.0 token endpoint to get an access token.

    Note

    To be able to get an access token, you must use the client credentials grant flow. An application with the client ID set to system is created for you in the System tenant by default. You can find the client secret that corresponds to your client application in your Cloudentity deployment configuration.

    Remember

    Your access token must have the manage_configuration scope added if there are any additional scopes assigned to the token.

    Even if there are no scopes defined in your request, it is good security practice to limit the scope assigned to the token.

    Learn More

    If you need help with getting the token, see the Getting started with Cloudentity REST API guide, section Call the token endpoint.

  2. Call the export configuration endpoint

    Request Example

    curl -o configuration.json --location --request GET 'https://{tid}/api/system/configuration' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}'
    

    The {tid} path parameter is your tenant identifier.

    Replace the {ACCESS_TOKEN} variable with the access token that you got in the first step.

Result

Your tenants' configuration is returned as a JSON in the request response body. You can copy and save it or use the -o configuration.json curl request parameter (as provided in the request example) to save the response body to a JSON file.

The file is saved in the current location you are at when sending the curl request.

Import Configuration

  1. Call the OAuth 2.0 token endpoint to get an access token.

    Note

    To be able to get an access token, you must use the client credentials grant flow. An application with the client ID set to system is created for you in the System tenant by default. You can find the client secret that corresponds to your client application in your Cloudentity deployment configuration.

    Remember

    Your access token must have the manage_configuration scope added if there are any additional scopes assigned to the token.

    Even if there are no scopes defined in your request, it is good security practice to limit the scope assigned to the token.

    Learn More

    If you need help with getting the token, see the Getting started with Cloudentity REST API guide, section Call the token endpoint.

  2. Call the import configuration endpoint.

    Request Example

    curl --location --request PUT 'https://{tid}/api/system/configuration' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -d @configuration.json
    

    The {tid} path parameter is your tenant identifier.

    Replace the {ACCESS_TOKEN} variable with the access token that you got in the first step.

    You can either paste your JSON tenant configuration to your request or point to the file that contains the configuration using the -d @YourFileName.json parameter. If you are using a file to provide the request body content, you must make the request from the location the file is placed in or provide a whole path to your file, for example -d @path/to/your/file/YourFile.json.

    Tip

    You can see that in the example request, the request body parameter points to the configuration file that was saved after the request to the export configuration endpoint.

    Before the import, you can, of course, modify the content of your configuration file and adjust it to your needs.

Result

Your global tenants configuration is imported and available within your Cloudentity deployment.

Insert Mode

Both import endpoints have the optional mode query parameter available. This parameter defines what happens if there are any conflicts when importing your tenant configuration. For example, if a client already exists within Cloudentity and you are trying to import a configuration that also has a client with this ID, there are the following ways Cloudentity can handle the request:

  • mode set to ignore - Cloudentity ignores the changes that come from your configuration import.

  • mode set to fail - Cloudentity stops import processing and returns an error.

  • mode set to update - Cloudentity updates the tenant’s configuration with the value provided in the request.

The default value for the mode parameter is ignore.

Configuration Management Using CLI

The import/export API is protected with the system tenant’s credentials. To be able to use the CLI, there are some prerequisites that you must meet. After you have everything set up, you are able to trigger the CLI with parameters like client identifier, client secret, and issuer url provided as arguments to the command.

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

  • --client-id which should be set to an identifier of the client application that is to be authenticated.

  • --client-secret which should be set to an secret of the client application that is to be authenticated.

  • --issuer-url which should be set to the issuer URL for the client application that gets authenticated. You can find the issuer URL for your tenant in your workspace settings.

Issuer URL, Tenant and Authorization Server Identifier

When using the import CLI, the issuer URL argument is used for client authentication and defining whether the import/export action is global or tenant-specific (to learn more, see note below).

There might be a case that Cloudentity is not able to retrieve tenant and authorization server identifier from the issuer URL, for example, when vanity domains are used to expose Cloudentity on a custom domain. To handle such cases, the CLI accepts the --tenant-id and --server-id arguments that you can pass with your import/export command to successfully enable the client application to authenticate.

Specifying if Import/Export is Global or Tenant-specific

As both the import or the export action can be global or tenant-specific, it is possible to define which option you want to use. Whether it is a global import/export or import/export for a specific tenant, it is defined using the --issuer-url argument.

If the issuer URL is set to a URL of a system tenant, the export/import action is global and applies for all tenants within your deployment.

If the issuer URL is set to a URL of a tenant different from the system tenant, the export/import action applies only to the configuration of the tenant with the issuer URL provided as the value for the --issuer-url argument.

When using the global export/import option, it is still possible to import/export configuration for one specific tenant. It is done by providing an additional argument to your export/import action called --tenant yourTenantID where you provide your tenant’s identifier. In this case, the issuer URL must be still set to a system tenant’s URL, but the configuration is exported/imported only for the tenant that is specified with the --tenant argument.

Prerequisites

  • Your Cloudentity must have a valid root certificate.

  • The integration_endpoints feature flag is enabled for your deployment.

  • Client application with:

    Client’s Tenant

    If you wish to export/import global configuration, the application must be created within the system tenant. If you wish to export/import configuration for a specific tenant, the client application can be created within the system workspace for your tenant.

    • Token Endpoint Authentication method set to client_secret_basic

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

    • manage_configuration scope.

      Your application must have this scope, as the CLI needs to be able to request it as both the import and the export actions are a part of the configuration management.

Import/Export Using CLI

  1. In terminal, navigate to the directory where you have your Cloudentity’s deployment binary files. Look for the acp binary file.

    Cloudentity on K8s

    For Cloudentity deployment on Kubernetes, you need to attach a bash shell to the pod where you have your Cloudentity deployed. You can do it by using the following kubectl exec -it {POD} -n {NAMESPACE} sh.

  2. For configuration export, run the following command:

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

    Configuration Format

    The configuration that you receive as the response can be in the JSON or YAML format. You can specify the desired format by using the --format argument. You can, for example, add --format yaml at the end of your export command.

    Passing Certificates

    To pass the certificate, you can use the certificate from your Cloudentity configuration file. You can do it by adding the --config path/to/your/config argument.

  3. For configuration import, run the following command:

    ./acp import --client-id {CLIENT_ID} --client-secret {CLIENT_SECRET} --issuer-url {ISSUER_URL} --input configuration.json
    

    The --input argument must contain either the filename of the configuration file (if you are executing the command from the same directory as where the file is located) or a path to your configuration file.

    Passing Certificates

    To pass the certificate, you can use the certificate from your Cloudentity configuration file. You can do it by adding the --config path/to/your/config argument.

CLI Help

If you need help with the syntax for the Cloudentity CLI, you can use the -h flag to trigger the reference guide for the CLI. You can, for example, check help for the export action by executing acp export -h in your terminal.