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.
Custom CMDB naming
The custom configuration database of an Identity Cloud service instance is named:
custom_{{ custom_name }}_cmdb
Custom CMDB access
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.
- Discuss with the Identity Cloud service instance customer account owner and Ubisecure to agree in advance who shall be authorized to access the custom configuration database.
- Familiarize yourself with Git. In order to customize an Identity Cloud service instance, you must know how to use Git. You can find comprehensive Git documentation and tutorials publicly available on the web.
- Create a user account (or use your existing account) with Bitbucket.org.
- Authorize your SSH public key with your user account. In order to customize an Identity Cloud instance, you must know how to configure your Git client to work with your SSH client software. You can find comprehensive documentation and tutorials on how to achieve this publicly available on the web.
- Send the user account name (or email address associated with the user account) to Ubisecure.
- Ubisecure will authorize your user account to access the custom configuration database.
Custom CMDB access management
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.
Custom CMDB directory structure
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:
- CustomerID product Configuration and Customization documentation
- SSO product Configuration and Customization documentation
- Ubisecure IAM Academy 4 training
Alternatively you can contact a Ubisecure expert partner for professional services to create an appropriate configuration for you.
- Ubisecure support is happy to help in case the product is not functioning as documented.
- Extended support and consulting services can be agreed separately, subject to availabilty.
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 # file: roles/sso7_server/vars/main.yaml ---
sso_api_configuration:
# Create site for a sample application
- method: "PUT"
path: "site/SSO%20API%20Sample"
# Link method to the site
- method: "PUT"
path: "site/SSO%20API%20Sample/$link/method/password.1"
# Create a group
- method: "PUT"
path: "group/SSO%20API%20Sample/Users"
# Make the group member of another group
- method: "PUT"
path: "group/SSO%20API%20Sample/Users/$link/memberOf/group/System/Administrators"
# Create a sample application
- method: "PUT"
path: "application/SSO%20API%20Sample/sample-app"
form:
enabled: "true"
# Allow group to the application
- method: "PUT"
path: "application/SSO%20API%20Sample/sample-app/$link/allowedTo/group/SSO%20API%20Sample/Users"
# Link method to the application
- method: "PUT"
path: "application/SSO%20API%20Sample/sample-app/$link/method/password.1"
form:
enabled: "true"
# Create attribute table (aka. authorization policy)
- method: "PUT"
path: "policy/SSO%20API%20Sample/sso-api-policy"
# Set the sample application metadata
- method: "PUT"
path: "application/SSO%20API%20Sample/sample-app/$attribute/metadata?policy=keep_client_credentials"
body:
redirect_uris:
- "https://api.example.test/sample-app/oauth2/response"
- "http://localhost/sample-app"
grant_types:
- "authorization_code"
- "password"
client_id: "sample-app"
client_secret: "---REDACTED---"
# Link attribute table to application
- method: "PUT"
path: "policy/SSO%20API%20Sample/sso-api-policy/$link/application/SSO%20API%20Sample/sample-app"
Specifying a |
Version numbers in directory names
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 branches
The custom configuration database by default has one branch only, namely the master branch.
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.
- Use a test service instance with different configuration sets at different times. Maintain each of the different test configuration sets in their separate branches.
- Use separate configuration branches for the current (before change) and new (after change) configuration sets for service transition in production.
The customer or integrator people are responsible for creating and managing the branches in their custom configuration database using standard Git branching features.
- Please consult the relevant sections in the publicly available Git reference documentation for instructions.
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, ... |
Alternative custom configuration branches must have identical file structure.
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.