Update OIDC-Based Authentication Configuration REST Service

Use the Update OIDC-Based Authentication Configuration REST Service to configure OpenID Connect (OIDC) authentication in IBM® Security Guardium® Key Lifecycle Manager container.

Operation
POST
URL
https://host:port/SKLM/rest/v1/authnConfigProperties/oidc

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

Request Parameters
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.
Request Headers
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.
Request body

JSON object with the following specification:

Property name Description
AUTH_TYPE_OIDC Specify true if you want to configure a supported OIDC provider for user authentication. Otherwise, by default, file-based authentication is available.

Other possible value is false.

OIDC_CONNECT_CLIENT_CLIENT_ID Specify the client ID of the OIDC provider to be connected to.
Note: This parameter is mandatory if you have specified true as a value in the AUTH_TYPE_OIDC parameter.
OIDC_CONNECT_CLIENT_SCOPE (Optional) Specify the OpenID Connect scope (as are detailed in the OpenID Connect specification) that is allowed for the provider.
OIDC_CONNECT_CLIENT_PROPAGATION (Optional) Specify whether the operation of the token inbound propagation of the OpenID relying party is to be controlled. Possible values:
  • supported - This is the default value.
  • none
  • required
OIDC_CONNECT_CLIENT_SERVER_USERIDENTIFIER Specify the JSON attribute in the ID token that is to be used as the user principal name in the subject. The possible values are sub (default value), email. Also, the value depends on the ID token.
OIDC_CONNECT_CLIENT_CLIENT_SECRET Specify the client secret of the OIDC provider to be connected to.
Note: This parameter is mandatory if you have specified true as a value in the AUTH_TYPE_OIDC parameter.
OIDC_CONNECT_CLIENT_SERVER_HOST Specify the host name or IP address of the OIDC provider.
Note: This parameter is mandatory if you have specified true as a value in the AUTH_TYPE_OIDC parameter.
OIDC_CONNECT_CLIENT_SERVER_PORT Specify the port number of the OIDC provider.
Note: This parameter is mandatory if you have specified true as a value in the AUTH_TYPE_LDAP parameter.
OIDC_CONNECT_CLIENT_SERVER_DISCOVERY_URL Specify the Discovery endpoint URL of the OIDC provider server.

If you do not specify this parameter, you must specify the following parameters: OIDC_CONNECT_CLIENT_SERVER_ISSUER, OIDC_CONNECT_CLIENT_SERVER_AUTH_URL, OIDC_CONNECT_CLIENT_SERVER_TOKEN_URL, OIDC_CONNECT_CLIENT_SERVER_USERINFO_URL, OIDC_CONNECT_CLIENT_SERVER_JWK_URL

If you use this parameter for configuration, Swagger UI is automatically configured to use the OIDC authentication.

OIDC_CONNECT_CLIENT_SERVER_ISSUER Specify the issuer identifier of the OIDC provider server.
OIDC_CONNECT_CLIENT_SERVER_AUTH_URL Specify the authorization endpoint URL. For example:
"oidc/endpoint/OP/authorize"
Note: This parameter is mandatory if you have specified true as a value in the AUTH_TYPE_LDAP parameter.
OIDC_CONNECT_CLIENT_SERVER_TOKEN_URL Specify the token endpoint URL. For example:
"oidc/endpoint/OP/token"
Note: This parameter is mandatory if you have specified true as a value in the AUTH_TYPE_LDAP parameter.
OIDC_CONNECT_CLIENT_SERVER_USERINFO_URL Specify the userInfo endpoint URL. For example:
"oidc/endpoint/OP/userinfo"
Note: This parameter is mandatory if you have specified true as a value in the AUTH_TYPE_LDAP parameter.
OIDC_CONNECT_CLIENT_SERVER_VALIDATION_METHOD Specify the validation method for the OIDC provider.

Possible values: introspect (default); userinfo

OIDC_CONNECT_CLIENT_SERVER_VALIDATION_URL Specify the validation endpoint URL for the OIDC provider. For example:
"oidc/endpoint/OP/introspect"
OIDC_CONNECT_CLIENT_SERVER_SIGNATURE_ALGORITHM Specify the signature algorithm that is used to verify the signature of the ID token. Possible values:
  • HS256 - Default value
  • RS256
OIDC_CONNECT_CLIENT_SERVER_JWK_URL Specify the JWK endpoint URL of the OIDC provider server.

Response

Response Headers
Header name Value and description
Status Code
200 OK
The request was successful. The response body contains the requested representation.
400 Bad Request
The authentication information was not provided in the correct format.
401 Unauthorized
The authentication credentials were missing or incorrect.
404 Not Found Error
The processing of the request fails.
500 Internal Server Error
The processing of the request fails because of an unexpected condition on the server.
Content-Type application/json
Content-Language Locale for the response message.
Success Response Body

JSON object with the following specification.

JSON property name Description
code Returns the success code.
status Returns a message that describes the status.
Error Response Body

JSON object with the following specification.

JSON property name Description
code Returns the application error code.
message Returns a message that describes the error.

Example

Specify OIDC configuration
POST https://localhost:port/SKLM/rest/v1/authnConfigProperties/oidc 
{
  "AUTH_TYPE_OIDC": "true",
  "OIDC_CONNECT_CLIENT_CLIENT_ID": "sklmRP_S1",
  "OIDC_CONNECT_CLIENT_CLIENT_SECRET": "secret",
  "OIDC_CONNECT_CLIENT_SERVER_DISCOVERY_URL": "https://host1/oidc/endpoint/OP/.well-known/openid-configuration",
  "OIDC_CONNECT_CLIENT_SERVER_VALIDATION_METHOD": "introspect",
  "OIDC_CONNECT_CLIENT_SERVER_VALIDATION_URL": "https://host1:443/oidc/endpoint/OP/introspect"
}
Success response
{
  "code": "CTGKM6206I",
  "status": "CTGKM6206I OIDC Configuration settings are updated."
}
Error response
{
  "code": "CTGKM6211E",
  "message": "CTGKM6211E Validation Endpoint test connection failed."
}
Table 1. Topic change log
Date Change description
20 Sept 2021 Corrected the example.
30 Sept 2021 Removed ckms from the REST endpoint.
10 Sept 2021 Initial version.