Configuring OpenID Connect

About this task

The system supports authentication against an OpenID Connect (OIDC) provider. When enabled, the IBM Cloud Object Storage Manager™ will support single sign-on via OIDC and OAuth 2.0 bearer tokens for REST API access. In OAuth 2.0/OIDC terms, the Manager is both a resource server and a relying party.

Note: OIDC providers may choose to implement all or part of the framework. While every effort has been made to verify support with various providers, the only official integration is withIBM Security™ Verify. In addition, the Manager only supports JSON Web Tokens (JWT) as OAuth 2.0 bearer tokens. Opaque bearer tokens are not supported.

Warning: The claims iss, sub, name, email, and email_verified must be present in all JWTs or available from the configured UserInfo endpoint. Otherwise, authentication may fail. Contact your OIDC provider administration to ensure all claims are in the tokens.

Note: For account or group creation or deletion, see Authentication and authorization.

Procedure

On the Settings tab, navigate to Authentication > OIDC.
1. If an OIDC provider is not configured, the ability to discover some required configuration values is provided.
  
  Note: Discovery is an optional step and requires communication with the provider. This may not be possible if the provider can only be reached via a proxy or requires a custom Certificate Authority. If you run into problems or wish to enter all config manually, it can be skipped at any point by clicking Next.
2. If prompted, enter the issuer URL and click Discover
  The Manager will attempt to download and parse the metadata document located at the issuer URL with the following path appended: /.well-known/openid-configuration
3. Discovered metadata is presented (e.g. Authorization Endpoint and Token Endpoint) and any value is carried over to the next screen.
  Any piece of metadata can be modified. However, this is usually not required.
4. Click Next.
Click Enable OIDC Authentication

Enter the configuration that matches the application’s configuration on the OIDC provider side. If discovery was executed, some values are pre-populated. The following information can be specified:

Table 1. Identity provider endpoints
Endpoint	Description
Issuer	A case-sensitive URL that unique identifies the OIDC provider.
Authorization	The provider’s endpoint that will perform authentication and authorization. Commonly used in the OAuth2.0 Authorization Code flow.
Token	The provider’s endpoint that returns Access Tokens, ID Tokens, and Refresh Tokens to the OIDC Relying Party.
UserInfo	The provider’s endpoint, protected by OAuth 2.0, that returns claims about the authenticated user.
JWKS URI	The URI where the provider publishes its public keys in JSON Web Key Set (JWKS) format. JWKS is used for signature verification.

Table 2. Token settings
Setting	Description
Group Claim	The JWT claim name that identifies the end-user’s group membership. The system expects the claim value to be a JSON array or a string.
Audience	The JWT claim value that identifies the Manager as the intended recipient of the JWT. Access tokens must contain this value when presented to the Manager.
ACR	The JWT claim value that represents the Authentication Context. If specified, the Manager will validate that all Access Tokens and ID Tokens contain an ACR claim with this value. This setting can be used to enforce that a certain policy (e.g. MFA) is applied prior to granting the end-user Manager access. Please see your OIDC provider documentation for details on supported ACR values.

Table 3. Client authentication
Field	Description
Client Authentication Scheme	The scheme that the Manager will use when authenticating with the OIDC provider at the token endpoint. The system supports the following schemes: Client secret basic Client secret POST Client secret JWT Private key JWT
Client ID	The unique public identifier supplied by the OIDC provider that identifies the Manager as a OIDC Relying Party.
Client Secret	TheManager’s secret supplied by the OIDC provider. You may need to specify the Manager as a Confidential Client in your provider’s administrative console to receive a secret. Note: If the OIDC provider is configured to sign ID or access tokens with an HMAC with SHA-2 algorithm, the secret MUST be at least the same size as the hash output. For example, HS256 requires a secret with at least 32 bytes. If it is not, the Manager will reject the token.
Key ID	The value of the “kid” header that will be in the Manager generated JWT in the Private key JWT client authentication scheme. This option is only visible if the Private key JWT is selected.
Private Key	The RSA private key that will be used to sign the Manager generated JWT in the Private key JWT client authentication scheme. The key must be at least 4096 bits. This option is only visible if the Private key JWT is selected.
CA Certificate	The optional list CA certificate(s) used to establish provider trust in Privacy Enhanced Mail (PEM) format. Each certificate must be a root CA certificate. This option is intended to be used when the provider is an on-premise solution. Leave this box empty if the provider is cloud-based.

Click the Proxy tab to enter a proxy that will be used for all communication with the provider.
1. Click Enable Proxy.
2. Enter the proxy URL. Only include the scheme (HTTP or HTTPS), domain, and port. If no port is specified, the default HTTP port 80 or HTTPS port 443 will be used.
3. Click Use Authentication and enter the username and password if the proxy requires HTTP basic authentication.
Note: If the proxy requires the tunnel to be set up using HTTPS (this is sometimes called a secure web proxy), you may need to specify a trusted certificate authority in the provided CA Certificate box. There is no separate location to specify trust for just the proxy. If you do so, you must also specify the provider’s CA certificate, as well, in the CA Certificate box.
Click Configure.