Skip to main content

Migrating tenants using import/export APIs

Learn how to use the import/export system APIs in order to migrate or promote a tenant.

Introduction

You can perform tenant migration with SecureAuth using our system export/import tenant configuration API.

These operations require system tenant access as you're going to be working with multiple tenants at the same time. For that reason, it's only possible in custom SecureAuth deployments.

Migrate a Tenant

  1. Acquire the system access token using the Client Credentials flow:

    CREDENTIALS="$(echo -n \"${CLIENT_ID}:${CLIENT_SECRET}\" | base64)"
  export SYSTEM_TOKEN=$(curl -k -X POST "${ENV_URL}/${TENANT_ID}/system/oauth2/token" \
      -H "Authorization: Basic ${CREDENTIALS}" \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      --data-raw 'grant_type=client_credentials&scope=manage_configuration' | jq -r ".access_token")

  2. In order to create a copy of a tenant, export the original configuration first.

    curl -k --request GET \
  --url https://example.com/api/system/configuration\?tid\=${TID} \
  --header "Authorization: Bearer $SYSTEM_TOKEN"

  3. Replace the tenant ID in the configuration file with a new tenant ID, for example:

    jq '.tenants[0].id = "TargetTenant"' data.json > data.json.tmp && mv -f data.json.tmp data.json

  4. In all objects related to the tenant, replace the tenant ID with the new one:

    sed -i s/'"tenant_id": "firsttenant"'/'"tenant_id": "secondarytenant"'/g data.json

  5. If you want to update URLs instead of regenerating them, you can run the command below:

    sed -i s,https://example.com/firsttenant,https://example.com/secondarytenant,g data.json

    Theoretically, you could just remove redirect URLs from JSON, and SecureAuth will generate them for you, but this wont work if you have provided custom URLs).

    Note that configuration export also contains secrets, rotated secrets, JWKS, and other sensitive data. If you want SecureAuth to regenerate this data on import, remove it from the file first.

  6. Having completed working on your configuration file for the new tenant, import the configuration:

    curl -k --request PUT \
  --url https://example.com/api/system/configuration \
  --header "Authorization: Bearer $SYSTEM_TOKEN" \
  -d @data.json

The new tenant is now imported.

Tenant migration using administrator APIs

In theory, you could execute this process using the administrator tenant APIs, but it's not recommended. In this case, the second tenant must already be created before import, which may cause some issues. For example, when you create the target tenant for import, some default data is created, (such as the demo workspace or demo client application). This data may have been removed in the exported tenant. The Update Tenant admin API, however, never removes any data, which means that in this scenario, the new tenant's configuration may be different from the original tenant.

Promote Tenant to New Environment

If you want to promote a tenant to a new environment, follow the instruction above. When replacing the URLs, you just need to make sure to correctly add the new environment URL.

In this section: