About Tenant Configuration
Cloudentity comes with possibilities to export and import tenant configuration. Cloudentity export/import APIs are available for 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 SaaS and on-premise Cloudentity versions:
-
Export tenant configuration to export a specific tenant configuration.
-
Import tenant configuration to import a configuration for a particular tenant.
Global operations are available for on-premise Cloudentity versions since the system tenant is available for on-premise deployments only.
Configuration File Format
All configuration import/export endpoints return/accept JSON with the configuration.
Exporting/Importing Tenant Configuration
Why import and export tenant configuration? Indeed, to simplify and speed up the process. Here are some key benefits:
-
To automate configuration.
-
To apply the ready-for-use configuration to another deployment for consistency.
-
To re-use a complicated configuration.
It comes in handy for companies delivering their services to financial institutions with Cloudentity as API protection. For example, they can duplicate an Open-Banking-directive-compliant tenant configuration from their deployment to their customer’s deployments.
Prerequisites
-
Access to the System workspace.
-
A client application that allows requests to the token endpoint within your System workspace.
To create the proper client application, go through the Preconfigure Your Workspace quickstart with two exceptions:
-
Carry out the steps within the System workplace instead of Admin.
-
Subscribe this client application to the
manage_configuration
scope.
-
As a result, your client application is set correctly, and you can make calls to export and import tenant configuration.
Export Tenant Configuration
-
Obtain an access token.
- Specify the
manage_configuration
scope when calling the token endpoint.
- Specify the
-
Call the export tenant configuration endpoint with the access token obtained.
Export Tenant Configuration Request Sample
curl -o {FileName.json} --location --request GET "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/api/system/$TENANT_ID/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 tenant configuration is returned as JSON in the response. The response includes configuration for all workspaces within the tenant and doesn’t include dynamic and non-configuration data. You can change this with optional request parameters.
Import Tenant Configuration
-
Obtain an access token.
- Specify the
manage_configuration
scope when calling the token endpoint.
- Specify the
-
Call the import tenant configuration endpoint.
Import Tenant Configuration Request Sample
curl --location --request PUT "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/api/system/$TENANT_ID/configuration" \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -d @$PATH/{FileName.json} // optional
Skip
-d $PATH/@{FileName.json}
when you pass the configuration directly within the request body.
As a result, your tenant configuration is imported and available within Cloudentity.
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 content received with the response 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.