Exporting, Importing and Patching Cloudentity Tenant/Workspace Configuration

The new Cloudentity configuration APIs provide four endpoints for managing workspace configuration.

The new Cloudentity configuration APIs provide four new endpoints, mirroring the workspace configuration APIs, for tenants.

The Tenant Management APIs can be used by organizations that need to manage many workspaces in their tenants or have a lot of tenant-level configuration such as: Cloudentity Identity Pools, Custom MFA Settings, Custom Themes, etc.

The new Cloudentity configuration APIs provide four new endpoints, mirroring the Tenant Configuration APIs for the Root System Workspace.

These new Root System configuration APIs could be used in lieu of the functionality previously referred to as Global operations.

These endpoints are only available for customer deployed Cloudentity, as the Root System Workspace is not directly available to SaaS Customers. The additional functionality provided by these endpoints is not relevant for SaaS customers.

The Customer Deployed Tenant Configuration APIs can be used to manage configuration of any tenant within Cloudentity deployment.

You can adjust the content received with the response upon calling the export endpoint, with the boolean parameter with_credentials.

By default, with_credentials = false.

Please consider the following limitations related to the new Export APIs:

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:

By default, mode = ignore.

Please consider the following limitations related to the Import APIs:

The patch endpoints support the mode query parameter. This parameter is optional; it defines what happens in the case of import conflicts. For example, when patching a configuration between two tenants, and both have client applications with identical IDs.

Cloudentity can handle this conflict as follows:

By default, mode = update.

Please consider the following limitations related to the new Patch APIs:

The Patch JSON API is intended for easy configuration changes when there are a small number of known workspace/tenant modifications and the user applying the patch is familiar with them.

The Patch JSON API accepts a JSON Array which objects represent a single operation applied to the target JSON (workspace configuration). Evaluation continues until all operations are successfully applied or until an error condition is encountered.

Example target configuration:

{
 "clients":{
    "sample-client-id":{
       "client_name":"sample-application",
       "response_types": [
            "code",
            "token"
       ]
    }
  }
}            

Example operation:

[
{ "op": "replace", "path": "/clients/sample-client-id/client_name", "value": "demo-application" },
{ "op": "add", "path": "/clients/sample-client-id/response_types", "value": "id_token" }
]            

Example result:

{
 "clients":{
    "sample-client-id":{
       "client_name":"demo-application",
       "response_types": [
            "code",
            "token",
            "id_token"
       ]
    }
  }
}            

The above operation results in replacing the current value of the client name parameter within the configuration of the client with the sample-client-id identifier. It also adds the id_token as the client application's response type.

The JSON Merge Patch API facilitates the automated promotion of larger configuration changes. It provides a straightforward and efficient way to apply extensive modifications, such as through scripts or automated methods. This API streamlines the process of implementing significant configuration updates, improving efficiency and accuracy.

The JSON Merge Patch API accepts a JSON that describes changes to be made to a target workspace/tenant configuration using a syntax that closely mimics the configuration being modified.

Example original configuration:

{
 "clients":{
    "sample-client-id":{
       "client_name":"sample-application",
       "response_types": [
            "token"
       ],
       "scopes": [
            "email",
            "profile",
            "openid",
            "offline_access"
       ]
    },
    "demo-client-id":{
     "client_name":"demo-application"
    }
  }
}            

Example JSON Merge Patch:

{
 "clients":{
    "sample-client-id":{
       "response_types": [
            "code",
            "token",
            "id_token"
       ],
       "scopes": [
            "email",
            "profile",
       ]
    },
    "demo-client-id": null
  }
}            

Example result:

{
 "clients":{
    "sample-client-id":{
       "client_name":"sample-application",
       "response_types": [
            "code",
            "token",
            "id_token"
       ],
       "scopes": [
            "email",
            "profile",
       ]
    }
  }
}            

You can see that the JSON Merge Patch API leaves the client name untouched, adds additional response types, and removes some of the scopes assigned to the client application. The demo application from the original configuration is removed completely from the ulting configuration.