Skip to main content

Exporting and Importing SecureAuth Tenants Configuration

Learn how to export and import SecureAuth tenant configuration with API. Upon reading this article, you will know how to export and import configuration when promoting your prepared and tested tenant from the staging environment to production and automate configuration.

About Tenant Configuration

SecureAuth comes with possibilities to export and import tenant configuration. SecureAuth export/import APIs are available for all deployment types and can be used, for example, to automate configuration.

Export/Import APIs

SecureAuth feature four endpoints to export and import tenant configuration.

Tenant-specific operations are available for both SaaS and on-premise SecureAuth versions:

Export and Import Deployment Configuration operations are available for on-premise SecureAuth versions since the system tenant is available for on-premise deployments only.

Note

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 SecureAuth as API protection. For example, they can duplicate an Open-Banking-directive-compliant tenant configuration from their deployment to their customer's deployments.

Prerequisites

  1. Access to the System workspace.

  2. 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

  1. Obtain an access token.

    • Specify the manage_configuration scope when calling the token endpoint.

  2. Call the export tenant configuration endpoint with the access token obtained. For example:

    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"

    Note

    -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

  1. Obtain an access token.

    • Specify the manage_configuration scope when calling the token endpoint.

  2. Call the import tenant configuration endpoint.

    Note

    Skip -d $PATH/@{FileName.json} when you pass the configuration directly within the request body.

    For example:

    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"

As a result, your tenant configuration is imported and available within SecureAuth.

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.

SecureAuth 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 to true when calling the export configuration endpoint.

In this section: