Page tree
Skip to end of metadata
Go to start of metadata

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.

  1. 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.
  2. 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.
  3. Create a user account (or use your existing account) with Bitbucket.org.
  4. 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.
  5. Send the user account name (or email address associated with the user account) to Ubisecure.
  6. 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 databaseDescription
.gitattributes
.gitignore
Git repository configuration files. Please refer to Git documentation.
roles/cid5_server/files/{{ custom_name }}/application/custom/backend.properties
roles/cid5_server/files/{{ custom_name }}/application/custom/eidm2.properties
roles/cid5_server/files/{{ custom_name }}/application/custom/mailmessages.properties
roles/cid5_server/files/{{ custom_name }}/application/custom/validation.json

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
roles/sso7_server/files/{{ custom_name }}/ubilogin/custom/messages/
roles/sso7_server/files/{{ custom_name }}/ubilogin/custom/resource.index
roles/sso7_server/files/{{ custom_name }}/ubilogin/custom/resources/
roles/sso7_server/files/{{ custom_name }}/ubilogin/custom/template.index
roles/sso7_server/files/{{ custom_name }}/ubilogin/custom/templates/

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
roles/sso7_server/files/{{ custom_name }}/ubilogin/webapps/uas/WEB-INF/web.xml

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 sso_api_configuration variable that is a list of SSO API calls using the following syntax:

# 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 form for a list item above will set the request Content-Type to application/x-www-form-urlencoded and URL-encode the content, whereas specifying a body will use Content-Type application/json and render the content in JSON.

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.

Control Desk update job parameters

Custom configuration is applied by running the update job for your Identity Cloud service instance on the Identity Cloud Control Desk.

  • Select the correct job and start the Build with Parameters.


PlaybookDescriptionTags
SSO custom configuration update
  1. Copies the Ubilogin custom files to SSO servers.
  2. If other SSO configuration files or templates have been configured, copies them as well.
  3. Sets the file permissions.
  4. Runs the Ubilogin SSO Tomcat update shell script.
  5. Restarts the Ubilogin servers.

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
  1. Copies the CustomerID application custom files to CustomerID servers.
  2. Sets the file permissions.
  3. Restarts the CustomerID application servers. CustomerID management console and API will have a service break for the duration of the restart.

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
  1. Copies the CustomerID import files to the CustomerID master server in a temporary import directory.
  2. Runs the CustomerID import shell script for each file in alphabetical order.

May affect the Ubilogin directory via the imported data only.

Selective control tags are not used with this playbook.
CustomerID LDIF import
  1. Copies the CustomerID LDIF files to the CustomerID master server in a temporary LDIF directory.
  2. Runs the LDAP modify command for each file in alphabetical order.

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.

Custom configuration branches

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.

  • 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_branchDescription
refs/heads/masterThis 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.