Update EKMF Web Configuration REST Service
Use the Update EKMF Web Configuration REST Service to define the EKMF Web configuration parameters in IBM® Security Guardium® Key Lifecycle Manager.
- Operation
POST
- URL
- https://host:port/SKLM/rest/v1/ckms/masterKey/EKMFWeb/config
By default, Guardium Key Lifecycle Manager server listens to the secure port 9443 (HTTPS) for communication. During IBM Security Guardium Key Lifecycle Manager installation, you can modify this default port.
Request
Parameter | Description |
---|---|
host | Specify the IP address or hostname of the IBM Security Guardium Key Lifecycle Manager server. |
port | Specify the port number on which the IBM Security Guardium Key Lifecycle Manager server listens for requests. |
Header name | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Authorization | SKLMAuth userAuthId=<authIdValue> |
Accept-Language | Any valid locale that is supported by IBM Security Guardium Key Lifecycle Manager. For example, en or de. |
JSON Object with the following specification.
JSON property name | Description |
---|---|
templateName | Required parameter. Specify the name of the key template that you created in EKMF Web. |
mTLS | Required parameter in a mTLS setup. Set this property to true
for mTLS communication between EKMF Web and GKLM. |
masterKeyAlias | Specify a custom alias for the master key. If no value is specified, by default the master key is created with an alias in the format KLMnKEY. Where, n is a number that automatically increments with every GKLM server that is configured with an EKMF Web host. For example, KLM1KEY, KLM2Key. The master key alias that you specify must contain only alphabets in uppercase and numbers and must be 7 characters long. For example, ALIAS123. Note: The master
key alias that you specify must contain only alphabets in uppercase and numbers and must be 7
characters long. For example, ALIAS123.
|
hostPreferenceSequence | Specifies the preference order in which GKLM connects to the configured EKMF Web hosts |
hosts | An array to specify EKMF Web hosts and their details. |
host | Hostname or IP address of the EKMF host. |
port | Port number to access the EKMF Web server. |
oidcUrl | URL of the OIDC server for authenticating to the EKMF Web server. |
clientId | Client ID. You can get this parameter value from the EKMF Web configuration. |
clientSecretPassword | Password associated with the client ID. You can get this parameter value from the EKMF Web configuration. |
username | Username of the EKMF Web server. You can get this parameter value from the EKMF Web configuration. |
password | Password associated with the username of the EKMF Web server. You can get this parameter value from the EKMF Web configuration. |
Response
Header name | Value and description |
---|---|
Status Code |
|
Content-Type | application/json |
Content-Language | Locale for the response message. |
JSON object with the following specification.
JSON property name | Description |
---|---|
code | Returns the code that is specified by the status property. |
status | Returns the status message that indicates whether the backup was successful.
|
JSON object with the following specification.
JSON property name | Description |
---|---|
code | Returns the application error code. |
message | Returns a message that describes the error. |
Examples
- Request for configuring a single EKMF Web host with GKLM:
-
POST https://localhost:port/SKLM/rest/v1/ckms/masterKey/EKMFWeb/config { "templateName": "ARV7GKLM", "mtls": "false", "masterkeyAlias": "MKEY123", "hosts": [ { "host": "ekmf1.mycompany.com", "port": "443", "oidcUrl": "https://oidc.ekmf1.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token", "clientId": "9a9e6df92ccf42d9b0c756312846ec98", "clientSecretPassword": "*******", "username": "oidc_username", "password": "*******" } ] }
- Success response
-
{ "status": "CTGKM0606I Update successful, change will take effect immediately" }
- Request for configuring multiple EKMF Web hosts with GKLM:
-
{ "templateName": "keytemplateTEST", "mtls": "false", "masterkeyAlias": "MKEY123", "hostPreferenceSequence": [ "ekmf1.mycompany.com", "ekmf2.mycompany.com", "ekmf3.mycompany.com" ], "hosts": [ { "host": "ekmf1.mycompany.com", "port": "443", "oidcUrl": "https://oidc.ekmf.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token", "clientId": "9a9e6df92ccf42d9b0c756312846ec98", "clientSecretPassword": "*******", "username": "oidc_username", "password": "*******" }, {"host": "ekmf2.mycompany.com", "port": "4443", "oidcUrl": "https://oidc.ekmf.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token", "clientId": "9a9e6df92ccf42d9b0c756312846ec98", "clientSecretPassword": "*******", "username": "oidc_username", "password": "*******" }, { "host": "ekmf3.mycompany.com", "port": "4443", "oidcUrl": "https://oidc.ekmf.mycompany.com/oidc/endpoint/EkmfOpenIdConnect/token", "clientId": "9a9e6df92ccf42d9b0c756312846ec98", "clientSecretPassword": "*******", "username": "oidc_username", "password": "*******" } ] }
- Success response
-
{ "status": "CTGKM0606I Update successful, change will take effect immediately" }
- Incorrect request example where OIDC URL is not specified:
-
POST https://host:9443/SKLM/rest/v1/ckms/masterKey/EKMFWeb/config { "templateName": "KeyTemplateTEST", "mtls": "false", "masterkeyAlias": "MKEY123", "hosts": [ { "host": "ekmf1.mycompany.com", "port": "19443", "clientId": "fefc57767d3c4e2cbbb3db35123f483d", "clientSecretPassword": "*******", "username": "oidc_username", "password": "*******" } ] }
- Error response
-
{ "code": "CTGKM0631E", "message": "CTGKM0631E Missing required parameter \" oidcUrl \" ." }