Configuring OIDC

Edit online

You can use the OpenID Connect (OIDC) to access the Administration Console, REST API and the IBM Verify Identity Governance - Container Service Center interfaces. The OpenID Connect provider must be able to authenticate the user and provide claims to a relying party about the authentication event and the user.

Before you begin

IBM Verify Identity Governance - Container supports OpenID Connect providers that meet the following requirements:

IBM Verify Identity Governance - Container is installed, configured and running.
The provider is fully OIDC-compliant.
The user registry is managed by IBM Verify Identity Governance - Container.
The relying party, IBM Verify Identity Governance - Container, is reachable from the provider.
IBM Verify Identity Governance - Container uses HS256 as the default OIDC token signature. If you want to use RS256 as the OIDC token signature, perform the following steps.
1. Load the CA certificate: Place the CA certificate in /config/certs directory with the name as oidc-aliasname.crt, where aliasname is the name you want to use for the alias.
2. Update config.yaml file: Open the config.yaml file. Go to the OIDC section. Provide the values for the following parameters:
  trustStoreRef=defaultTrustStore
  
  trustAliasName=aliasname where, aliasname must be the same as you specified as filename in the above step.
Ensure that you configured an OpenID Connect provider such as IBM® Security Verify or IBM Security Verify Access.

Steps to configure IBM Security Verify

Create a custom application. For details, see Managing your applications
Configure the application for OpenID Connect single sign-on. For details, see Configuring OpenID Connect single sign-on in the custom application
To enable Multi-Factor Authentication (MFA) for the application, see Enabling MFA for applications

You need the following information to perform OpenID operations.

Table 1. General configuration
Parameter	Description
scope	The scopes that are associated with access tokens determine what resources are available when they are used to access OpenID connect protected endpoints. The following example is a non-normative example of scope: `scope=openid profile email phone`.
authorizationEndpointUrl	The initial endpoint that is contacted by the relying party to begin a flow.
tokenEndpointUrl	The endpoint that is used to exchange an authorization code for a token.
signatureAlgorithm	The algorithm that is used to sign the ID token that is issued by a provider. The default value is `HS256`.
issuerIdentifier	The verifiable identifier for an issuer. An issuer identifier is a case-sensitive URL that uses the HTTP scheme. It contains scheme, host, and optionally, port number and path components. It cannot contain query or fragment components.
userIdentityToCreateSubject	Specifies a JSON attribute in the ID token that is used as the user principal name in the subject. If no value is specified, the JSON attribute "`sub`" is used.
trustAliasName	The label of the certificate that was uploaded to the trust store. Select an appropriate label.
redirectUri	You must register a redirect URI at the OpenID provider. After a successful authentication at the OpenID provider, the client is redirected to this URL
logoffUrl	The OpenID Connection provider logout URL. For example, the ADFS logout url is `https://<hostname>/adfs/oauth2/logout` By providing a logout URL after logging out from the selected Interface, IBM Verify Identity Governance - Container cleans all OpenID Connect provider tokens. If you do not provide an OpenID Connect provider logout URL, then logout only cleans IBM Verify Identity Governance - Container application tokens.

Apart from the General Configuration parameters, if you want to update other parameters and values, then you can refer those from IBM WebSphere Liberty OpenID Connect Client page, see this documentation.

Procedure

Refer the OpenID provider document and make the configuration so that it can be used as an OpenID connect provider. Implement the configuration such that IBM Verify Identity Governance - Container will be registered as relying party.
The OpenID provider certificate must be added to the IBM Verify Identity Governance - Container truststore.
1. Download the OpenID connect provider certificate.
2. Ensure that the certificate file is placed in the config/certs directory.
3. Edit the config/config.yaml file and in the server > truststore section, specify the name of the certificate file. Example:
```
server:
 truststore:
 - '@idpCert.crt'
```
  Here, idpCert.crt is the name of OpenID provider certificate file.
Continue with editing the config/config.yaml file to append an oidc section. Create required sub-sections under oidc based on interface for which OIDC needs to be enabled. Specify the configuration parameters with their values.
Note: The OIDC feature is only enabled for the interfaces for which the configuration is added to the oidc section in the config.yaml file. The current login will continue for the remaining interfaces.
The oidc section with sub-sections for all interfaces in config.yaml file will have the following structure. You can either configure the same OpenID service provider for all the interfaces, or you may configure different OpenID service providers for each of the interfaces.
Important: Ensure proper indentation of the sections, sub-sections, and parameters. The "-" should be directly under the first letter of each category header. Incorrect indentation may cause failure of config.yaml file processing.
```
oidc: 
 adminConsole:
 - parameterName=parameterValue
 - parameterName=parameterValue
 - parameterName=parameterValue
 isc:
 - parameterName=parameterValue
 - parameterName=parameterValue
 - parameterName=parameterValue
 rest:
 - parameterName=parameterValue
 - parameterName=parameterValue
 - parameterName=parameterValue
```
Note: The clientId and clientSecret MUST not be specified as part of config.yaml file. These values should be provided when prompted by the changePasswords.sh script, as discussed later in this topic.
Here is an example to enable OIDC for Service Center, using IBM® Security Verify Access (ISVA) as an OpenID Connect provider.
```
oidc:
 isc:
 - scope=openid
 - authorizationEndpointUrl=https://<ISVA_HOSTNAME:PORT>/mga/sps/oauth/oauth20/authorize
 - tokenEndpointUrl=https://<ISVA_HOSTNAME:PORT>/mga/sps/oauth/oauth20/token
 - signatureAlgorithm=HS256
 - issuerIdentifier=https://<ISVA_HOSTNAME>
 - userIdentityToCreateSubject=sub
 - trustAliasName=idpCert
 - redirectUri=https://<IM_HOSTNAME:PORT>/oidcclient/redirect/isc
 - logoffUrl=https://<ISVA_HOSTNAME:PORT>/mga/sps/oauth/oauth20/logout
```
Here is an example to enable OIDC for Service Center, using IBM® Security Verify as an OpenID Connect provider.
```
oidc:
  isc:
    - scope=openid
    - authorizationEndpointUrl=https://<yourtenant.verify.ibm.com>/v1.0/endpoint/default/authorize
    - tokenEndpointUrl=https://<yourtenant.verify.ibm.com>/v1.0/endpoint/default/token
    - signatureAlgorithm=HS256
    - issuerIdentifier=https://<yourtenant.verify.ibm.com>/oidc/endpoint/default
    - userIdentityToCreateSubject=sub
    - trustAliasName=isv-saas
    - redirectUri=https://<IM_HOSTNAME:PORT>/oidcclient/redirect/isc
    - logoffUrl=https://<yourtenant.verify.ibm.com>/idaas/mtfim/sps/idaas/logout
```
If you want to enable OIDC only for Service Center, then you only need to add the isc section with parameter values.
Run the starter/bin/changePasswords.sh script with oidc as an argument.
Example: starter/bin/changePasswords.sh oidc.
The values for clientId and clientSecret should be provided when prompted by the script.
Restart IBM Verify Identity Governance - Container pods for changes to take effect.
Example: kubectl -n isvgim rollout restart statefulset isvgim
Here, isvgim indicates your Kubernetes namespace for IBM Verify Identity Governance - Container.
NOTE: When OpenID Connect Configuration is enabled, do not modify the following properties manually:
- enrole.ui.disableLoginPage property in ui.properties file
- ui.isc.oidcEnabled property in ui.properties file
- ui.disableLoginPage property in UIconfig.properties file