OpenID Connect (OIDC) is the new Internet Single Sign-on (SSO) protocol based on OAuth 2.0 specifications. Using OIDC, a client can request the userâ€™s identity as an ID token in a standardized REST-like manner, and it can use the access token to access protected REST-like Services. This article discusses some advanced use scenarios and tips, and lists some resources for further reading on Liberty OpenID Connect.
WAS Liberty can be set up as an OpenID Connect Provider or an OpenID Connect Relying Party:
- Liberty OIDC provider
A dedicated Liberty instance can be configured as an OIDC provider (OP) and a Single Sign-on (SSO) server. Any client application can call an OP-hosted RESTful security service to request or verify end user identity and user profiles.
- Liberty OIDC relying party
A Liberty instance can be configured as an OIDC relying party to take advantage of web SSO and use any OIDC provider as an identity provider.
Advanced usage scenarios
Tips on how to implement some common usage scenarios…
Setting up an OIDC relying party to support multiple tenants
One Liberty server acting as an OpenID Connect relying party can sign on with multiple OpenID Connect providers. You create multiple
openidConnectClient elements and multiple authentication filters. Each
openidConnectClient element defines one Single-Sign-On relationship between Liberty and one OpenID Connect Provider. For example, you can configure users whose IP address in range
192.168.*.* to login with Liberty OP, and IP address in range
192.128.*.* to login with Google OP.
Setting up an OIDC provider to support multiple tenants
A Liberty server acting as OP can be configured to support multiple tenants by configuring multiple
openidConnectProvider elements. Each
openidConnectProvider defines an unique OP instance that has its own endpoint, authentication policy and login form, consent form and consent policy, token life time, and other OP specific configurations. The
openidConnectProvider must be unique, and is included in the OPâ€™s endpoint URL.
Setting up an OIDC provider to delegate user authentication to another OIDC provider
A Liberty OpenID Connect provider can delegate user authentication to a third-party OpenID Connect provider. To enable this authentication delegation, you configure the OP as an OpenID Connect relying party. This scenario is useful if you have many clients, and each client needs to work with different OPs. Instead of having each client deal with different OPs, you set up one Liberty OP as a gateway to invoke different OPs.
Running an OIDC relying party and an OIDC provider behind different firewalls
The Liberty OpenID Connect client and Liberty OpenID Connect provider support the OAuth 2.0 Form Post Response Mode specification. When you configure the Liberty OpenId Connect client to use implicit grant type and
response_mode=form_post, it can participate in web Single-Sign-on with an OpenID Connect provider that is running in a different firewall.
Creating custom ID tokens
A Liberty OIDC OP emits an ID token that contains all required claims as defined in the specification. Additionally, a Liberty OPâ€™s ID token include
realmName claims that can be used by the relying party to create a subject for authorization.
A Liberty OIDC OP also provides a plug-in point to further customize the ID token based on security attributes in the authenticated subject. If you want to put a security attribute as custom claim in an ID token, you need do two things:
- Make sure the Subject’s
com.ibm.wsspi.security.oidc.external.claimsattribute, which contains a Map of security attributes required in id token.
- Add the
externalClaimNames, and set its value to the required security attribute names delimited by white space.
For example, if
com.ibm.wsspi.security.oidc.external.claimscontains attribute of tenant, role, job, phone, and address, setting
externalClaimNames=â€ťtenant role jobâ€ťwill let the OP extract the security attributes tenant, role, and job from the subject, and assert them as claims to the ID token.
Persistent OIDC tokens in an OIDC provider
A Liberty OP provides a quick start-up mode by storing registered clients in
server.xml and tokens in memory. However, we would expect most production systems will store clients and tokens in a database. To get into persistent mode, you configure
databaseStore. In persistent mode, registered clients, access token, ID token, refresh token, and user consent are stored in a database. Tokens and user consents are persistent and are automatically recovered even after OP restart. The full functions of client registration endpoint – including
delete – are available only in
Liberty OIDC resources for further reading
- OpenID Connect specifications
- Tutorial: Liberty OIDC architecture, functions, and configuration
- Tutorial: How to set up OpenID Connect web Single-Sign-on with Google
- Video: OpenID Connect Quick Setup
- Video: OpenID Connect Quick Setup with Google OP
- Knowledge Center documentation: Using OpenID Connect