Defining UKO configuration properties in IBM Guardium Key Lifecycle Manager

Define the Unified Key Orchestrator (UKO) configuration properties in IBM Guardium Key Lifecycle Manager by using the REST interface.

About this task

To configure UKO, you must define the following parameters in the IBM Guardium Key Lifecycle Manager:
Table 1. UKO parameters
Parameter Description Sample value
masterKeyAlias Specify the label of master key that is created in UKO as alias. The master key alias that you specify can contain only alphabets in uppercase and numbers. You can use the special character such as period (.) and must not exceed a length of 64 characters.
Note: Ensure that the master key is correct because after the master key alias is configured, it cannot be changed directly. If you want to change the master key alias, first migrate the master key store from UKO to JCEKS and then reconfigure UKO with the desired master key alias.
 MKEY123
hostPreferenceSequence Specifies the preference order in which IBM Guardium Key Lifecycle Manager connects to the configured UKO hosts. 
hostPreferenceSequence": [ "uko1.mycompany.com", "uko2.mycompany.com" ]
hosts List of hosts and their details. 
"hosts": [ 
{ "host": "uko1.mycompany.com", 
"port": "443", 
"oidcUrl": "https://oidc.uko.mycompany.com/oidc/endpoint/UKOOpenIdConnect/token", 
"clientId": "9a919tf53ccf42d9b0c756312846ec98", 
"clientSecretPassword": "*******", 
"username": "testuser", 
"password": "*******" } ]
host Hostname or IP address of the UKO server. uko_server_hostname
port Port number to access the UKO server. 443
oidcUrl URL of the OIDC server for authenticating to the UKO server. https://oidc-server/oidc/endpoint/UKOOpenIdConnect/token
clientId Client ID. You can get this parameter value from the UKO configuration. client1
clientSecretPassword Password associated with the client ID. You can get this parameter value from the UKO configuration. client1_password
username Username of the UKO server. You can get this parameter value from the UKO configuration. user1
password Password associated with the username of the UKO server. You can get this parameter value from the UKO configuration. user1_password

Procedure

  1. Open the Swagger UI. For more information, see Using Swagger UI.
  2. Authenticate and authorize to access the REST APIs. For more information, see Authentication process for REST services.
  3. Go to the Master key management section.
  4. Run the Update UKO Configuration Settings REST Service to define the UKO parameters in IBM Guardium Key Lifecycle Manager. To specify a custom master key alias, use the masterkeyAlias parameter.
    Note: In an OIDC authentication setup, ensure that the mtls parameter is set to false. Also, ensure that the master key alias is correct as it cannot be changed directly after it is configured. If you want to change the master key alias, first migrate the master key from UKO to JCEKS, and then reconfigure UKO with the desired master key alias.
    Configuring a single UKO host
    POST GKLM/rest/v1/ckms/masterKey/UKO/config
{
    "mtls": "false",
    "masterkeyAlias": "GKLM.MKEY.KEY123",
    "hosts": [
        {
            "host": "uko1.mycompany.com",
            "port": "443",
            "oidcUrl": "https://oidc.uko.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token",
            "clientId": "9a919tf53ccf42d9b0c756312846ec98",
            "clientSecretPassword": "*******",
            "username": "testuser",
            "password": "*******"
        }
    ]
}
    Configuring multiple UKO hosts
    To configure multiple UKO hosts, specify the UKO hosts and their details in the hosts parameter in comma-separated format.
    POST GKLM/rest/v1/ckms/masterKey/UKO/config
{
    "mtls": "false",
    "masterkeyAlias": "GKLM.MKEY.KEY123",
    "hosts": [
        {
            "host": "uko1.mycompany.com",
            "port": "443",
            "oidcUrl": "https://oidc.uko.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token",
            "clientId": "9a919tf53ccf42d9b0c756312846ec98",
            "clientSecretPassword": "*******",
            "username": "testuser",
            "password": "*******"
        }
        {
            "host": "uko2.mycompany.com",
            "port": "443",
            "oidcUrl": "https://oidc.uko.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token",
            "clientId": "9a919tf53ccf42d9b0c756312846ec98",
            "clientSecretPassword": "*******",
            "username": "testuser",
            "password": "*******"
        }
    ],
    "hostPreferenceSequence": [ 
            "uko1.mycompany.com", 
            "uko2.mycompany.com" 
     ]
}
  5. To view the configured UKO details, run the Get UKO Configuration Settings REST Service. 
    GET https://host:9443/GKLM/rest/v1/ckms/masterKey/UKO/config

What to do next

Complete steps 3 and 4:

Step 3: Import the UKO certificate and OIDC server certificate. When you import the UKO certificate, for the Trust this certificate for field, choose UKO. Similarly, for the OIDC certificate choose OIDC. For instructions, see Importing a system peripheral certificate.

Step 4: Set up the master key in UKO. For instructions, see Setting up the master key in Unified Key Orchestrator.