Current versions of the Identity Server software require some customization based on configuration files under the service installation directory. For manageability and security reasons, the customer or integrator does not have direct access to the file system where these configuration files must be installed. Instead, service instance customization is done by creating and editing the necessary files in a version control repository dedicated for the service instance. This repository is also known as the custom configuration database.
Each Identity Cloud service instance has a custom configuration database dedicated to that instance only. |
Ubisecure Operations creates the custom configuration database for each Identity Cloud service instance.
The custom configuration database of an Identity Cloud service instance is named:
custom_{{ custom_name }}_cmdb
For easy access to the custom configuration database, we recommend well-known private Git repository services on the cloud.
Typically the custom configuration database will be available at a Git remote address such as:
git@bitbucket.org:gs-iam/custom_{{ custom_name }}_cmdb.git
Ubisecure provides the customer or integrator with the exact address of the custom configuration database.
The customer or integrator people are responsible for creating a user account with the Git service provider. These are the people who will be implementing the Identity Cloud service instance customization.
The customer is responsible for requesting user management actions, such as adding, changing, or removing a user's access to the custom configuration database. Ubisecure will implement the user management actions as requested by the customer. |
After your user account has been authorized for access to the custom configuration database, you can clone it using the Git remote address given.
Understanding the configuration items in the Identity Cloud custom configuration database requires know-how to customize the Identity Server products. You can familiarize yourself with the subject via the following resources:
Alternatively you can contact a Ubisecure expert partner for professional services to create an appropriate configuration for you.
The custom configuration database directory structure is as follows:
Relative path inside the custom configuration database | Description | |
---|---|---|
.gitattributes | Git repository configuration files. Please refer to Git documentation. | |
roles/cid5_server/files/{{ custom_name }}/application/custom/backend.properties | CustomerID application custom configuration files Please refer to the CustomerID Configuration and Customization documentation. | |
roles/cid5_server/files/{{ custom_name }}/import/001-initial.import | CustomerID initial data import files These data will be imported upon fresh installation of the service instance – typically before the service is taken into actual use. Use of this import mechanism is not recommended after the initial installation. Please use the appropriate import APIs and client-side tools instead. | |
roles/sso7_server/files/{{ custom_name }}/import/001-initial.ldif | SSO initial data import files | |
roles/sso7_server/files/{{ custom_name }}/ubilogin/custom/message.index | SSO custom configuration files Please refer to the SSO Configuration and Customization documentation. | |
roles/sso7_server/files/{{ custom_name }}/ubilogin/webapps/uas/WEB-INF/jsp/success.jsp | Examples of web application customization by replacing chosen files | |
roles/sso7_server/templates/{{ custom_name }}/ubilogin/webapps/ROOT/node.txt.j2 | Example of an SSO node identification template at the web application context root | |
roles/sso7_server/vars/main.yaml | SSO custom configuration variables in YAML format May specify the
Specifying a |
Note that the directory naming does not necessarily follow the exact version of your Identity Server software. The number used in the directory names refers to the earliest version when the configuration structure was taken into use. The same structure may be used for several subsequent product versions. |
Custom configuration is applied by running the update job for your Identity Cloud service instance on the Identity Cloud Control Desk.
Playbook | Description | Tags |
---|---|---|
SSO custom configuration update |
This playbook operates on one SSO server at a time to minimize the likelihood of a service break. In a high availability configuration, the other SSO server should be serving normally while the other is being updated. A single server failing to restart does not have to cause a service break. Current sessions may be affected by failover. It is possible to make breaking changes which allow the servers to restart, but still cause a service break until the breaking changes have been corrected. | Selective control tags are usually not needed with this playbook. The tags 'custom', 'tomcat', or 'restart' can be used to perform only that part of the update. |
CustomerID custom configuration update |
If the user has made breaking changes in the custom configuration, CustomerID may fail to restart until the breaking changes have been corrected. Does not affect the SSO servers. | Selective control tags are usually not needed with this playbook. The tag 'custom' or 'restart' can be used to perform only that part of the update. |
CustomerID data import |
May affect the Ubilogin directory via the imported data only. | Selective control tags are not used with this playbook. |
CustomerID LDIF import |
May affect the Ubilogin directory via the imported data only. | Selective control tags are not used with this playbook. |
The Identity Cloud runs the same Identity Server software that you would run on-premises. For more information, please refer to the Identity Server product documentation.
The custom configuration database by default has one branch only, namely the master
branch.
Using a single custom configuration set is recommended for simplicity. Only a single custom configuration can be active at a time per Identity Cloud service instance. |
The customer may request Ubisecure to enable Custom configuration branches support for an Identity Cloud service instance.
This enables the creation of alternative configuration branches for the same service instance for testing or service transition purposes.
The customer or integrator people are responsible for creating and managing the branches in their custom configuration database using standard Git branching features.
The custom configuration branch must be then specified when deploying custom configuration updates.
custom_cmdb_branch | Description |
---|---|
refs/heads/master | This is the default when only one configuration set is used. |
refs/heads/<branchName> | Tracks/checks out the specified branch. E.g. refs/heads/master, refs/heads/feature1/master, ... |
refs/tags/<tagName> | Tracks/checks out the specified tag. E.g. refs/tags/iam-2.3.0 |
<commitId> | Checks out the specified commit. E.g. 5062ac843f2b947733e6a3b105977056821bd352, 5062ac84, ... |
If the configuration includes customization of arbitrary files, all those files must exist in all configuration branches. You cannot delete — only replace — files between different configuration branches. |