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 id for 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 groupIds, uniqueSecurityName, and 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:

  1. Make sure the Subject’s PublicCredentials contains com.ibm.wsspi.security.oidc.external.claims attribute, which contains a Map of security attributes required in id token.
  2. Add the openidConnectProvider configuration attribute externalClaimNames, and set its value to the required security attribute names delimited by white space.
    For example, if com.ibm.wsspi.security.oidc.external.claims contains 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 create, read, update, and delete – are available only in databaseStore mode.

Liberty OIDC resources for further reading

3 comments on"How to learn and use WAS Liberty OpenID Connect"

  1. Hi, Chunlong
    Thanks for prompt response. And it works for me. Somehow your sample application binding is not visible here. I put my sample application binding here for other people’s reference.

  2. Chunlong Liang April 12, 2016

    Here is a sample application binding

  3. Hi, I have setup two liberty profile server (v8.5.5.9), one as OP, the other one as OIDC relying party. For Liberty OIDC provider, I use custom user registry for authentication. From OIDC token endpoint, I could get the access token, refresh token and ID token as follows:
    {“access_token”:”yt3T890nwaBepptycYxFmDXz1JDIi2iHF1SHUTwu”,”token_type”:”Bearer”,”expires_in”:7199,”scope”:”openid profile email”,”refresh_token”:”ttYpurkfYURpw
    JfzZMBdXf3bzIjskB7p06gMDESmeoUBsd8dsU”,”id_token”:”eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczovL2xvY2FsaG9zdDo4NDQzL29pZGMvZW5kcG9pbnQvbGliZXJ0eV9vcDIiLCJhdF9oYXNo
    IjoieEhRbWtwOTYzdHh4YnlMelhBa21RdyIsInN1YiI6InVzZXIxIiwiYXVkIjoibGliZXJ0eV9ycDIiLCJyZWFsbU5hbWUiOiJjdXN0b21SZWFsbSIsInVuaXF1ZVNlY3VyaXR5TmFtZSI6IjUwMSIsImdyb3Vw
    SWRzIjpbIjAwMSJdLCJleHAiOjE0NjA0Mzk0NDEsImlhdCI6MTQ2MDQzMjI0MX0.zMfVNEJyuUX38wfaF_mn7AFDnAc2fxr2EYrLMPwrBHg”}
    After decoding, the id token is –> {“iss”:”https://localhost:8443/oidc/endpoint/liberty_op2″,”at_hash”:”xHQmkp963txxbyLzXAkmQw”,”sub”:”user1″,”aud”:”liberty_rp2″,”realmName”:”customRealm”,”uniqueSecurityName”:”501″,”groupIds”:[“001″],”exp”:1460439441,”iat”:1460432241}

    My problem is that at OIDC relying party, I could not map the security-role using the user name or group name, which is actually included in the ID token.

    The following exceptions are reported
    [4/12/16 13:43:28:040 SGT] 0000003e com.ibm.ws.logging.internal.impl.IncidentImpl I FFDC1015I: An FFDC Incident has been created: “com.ibm.ws.security.registry.RegistryException com.ibm.ws.security.appbnd.internal.authorization.AppBndAuthorizationTableService 334” at ffdc_16.04.12_13.43.28.0.log
    [4/12/16 13:43:28:054 SGT] 0000003e .ibm.ws.webcontainer.security.WebAppSecurityCollaboratorImpl A CWWKS9104A: Authorization failed for user user1 while invoking testpage on /. The user is not granted access to any of the required roles: [All Role].

Join The Discussion

Your email address will not be published. Required fields are marked *