Exporting and importing ACP tenants configuration
Learn how to export and import ACP tenant's configuration using API and built-in ACP command line interface (CLI), which is available for on-premise deployments. You can move tenants' configuration between your different ACP deployments, or use it for configuration automation. You can also export and import the entire ACP configuration for all tenants.
About working with tenant configuration
ACP comes with a few possibilities on how you can export or import your tenants' configuration. ACP export/import APIs are available for all deployment types and can be used, for example, for configuration automation. ACP’s built-in command line interface (CLI) can be used by on-premise deployments of Authorization Control Plane.
Import/Export APIs
With ACP system API you can export and import your tenants' configuration. There are four dedicated endpoints that allow you to do that:
-
Export configuration that allows you to globally export your entire ACP deployment configuration for every tenant.
-
Import configuration that allows you to globally export your entire ACP deployment configuration for every tenant.
-
Export tenant configuration that allows you to export a specific tenant’s configuration only.
-
Import tenant configuration that allows you to import a configuration for a specific tenant only.
Note
All of the configuration import/export endpoints return/accept JSON with the configuration.
Import/Export CLI
The ACP’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 ACP 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 ACP deployments. A company that delivers its services to financial institutions and uses ACP 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
-
You have access to the system workspace.
-
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 ACP 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
-
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 ACP REST API guide, section Call the token endpoint.
-
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 the configuration
-
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 ACP REST API guide, section Call the token endpoint.
-
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 ACP.
Exporting/importing global tenants configuration
Customers that use the on-premise version of the ACP deployment can use the global tenants' configuration export/import ACP 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
-
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 ACP 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 ACP REST API guide, section Call the token endpoint.
-
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 the configuration
-
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 ACP 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 ACP REST API guide, section Call the token endpoint.
-
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 ACP 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 ACP and you are trying to import a
configuration that also has a client with this ID, there are the following ways
ACP can handle the request:
-
mode
set toignore
- ACP ignores the changes that come from your configuration import. -
mode
set tofail
- ACP stops import processing and returns an error. -
mode
set toupdate
- ACP 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 argument and 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 ACP is not able to retrieve tenant and authorization server identifier from the issuer URL, for example, when vanity domains are used to expose ACP 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 ACP 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 ACP 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
-
In terminal, navigate to the directory where you have your ACP’s deployment binary files. Look for the
acp
binary file.ACP on K8s
For ACP deployment on Kubernetes, you need to attach a bash shell to the pod where you have your ACP deployed. You can do it by using the following
kubectl exec -it {POD} -n {NAMESPACE} sh
. -
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 ACP configuration file. You can do it by adding the
--config path/to/your/config
argument. -
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 ACP 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 ACP 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 executingacp export -h
in your terminal.