Added Support for OIDC User Info and Token Endpoint Response

The 7/25/2020 nightly release of Ignition 8.0.16 introduces first-class support for OIDC IdPs to call the User Info API. Additionally, the token endpoint response object is now exposed to user attribute mappers, security level rules, and Perspective sessions.

User Info

The OIDC spec defines an HTTP endpoint which may be optionally exposed by IdPs. Relying party applications (such as Ignition) may optionally call this endpoint to retrieve additional claims about the authenticated user which may not exist in the ID token’s claims.

If your IdP supports the User Info endpoint and you would like to configure Ignition to call this endpoint for each authentication, go to your IdP’s settings in the Gateway Config Page and fill in the URL to the endpoint (or re-import the OIDC IdP’s metadata to have it automatically filled), then save. If your IdP does not support this endpoint or you do not want Ignition to call the endpoint for each authentication, leave it blank. This field will be blank on upgrade.

Token Endpoint Response

The Ignition Gateway’s OIDC implementation authenticates users by following the Authorization Code Flow. At a high level, this involves the following:

  1. Ignition redirects the user to the OIDC IdP login page
  2. User successfully logs into the OIDC IdP
  3. OIDC IdP redirects the user back to Ignition with an auth code
  4. Ignition makes a back-channel call to the OIDC IdP’s token endpoint and passes the auth code from the user
  5. The OIDC IdP returns a token endpoint response which contains the ID token (used to identify who the user is) as well as an access token (can be used to call other web-based APIs protected with OAuth2 bearer tokens such as the user info API) and other properties.

Before this nightly release, it was not possible to use the token endpoint response from step 5 above. Now you may use this object in user attribute mappers, security level rules, and perspective sessions. The most obvious use case for this is to be able to pull out the access token which may be used to authorize requests made by Ignition to resource servers protected by the same OIDC IdP used by Ignition to authenticate the user. You could also potentially use the ID token to pass along to other APIs as a way to authenticate the user depending on whether or not your IdP and resource servers support this kind of model. The refresh token could be used to call the token endpoint before the last token has expired in order to get a fresh set of tokens without having to send the user back to the IdP, again depending on whether or not your IdP and resource server support this capability.

Direct User Attribute Mappers

Direct user attribute mappers will now have a new drop down to pick the source of user attributes (i.e. ID Token Claims, Token Endpoint Response, User Info Claims). If an OIDC IdP does not have a user info endpoint configured, it should not be possible to select the user info claims source in the drop down (it should not even appear as an option unless it was configured beforehand). Since ID Token Claims were the only source of user attributes before, this is the default selected on upgrade.

Expression User Attribute Mappers

Expression user attribute mappers will continue to support the expression it supports from before (for backwards-compatibility), but a new expression path prefix was added to support multiple sub sources of attributes by name. The format works like this: {attribute-source:(subSourceNameHere):(pathToAttributeHere)} . For example: {attribute-source:idTokenClaims:email} will pull the value from the ID Token Claims attribute source json object with property name email.

Security Level Rules

The same goes for security level rules as explained for expression user attribute mappers (above), including the note about backwards-compatibility as well as the new expression path format for accessing multiple attribute sub-sources.

Perspective Session Props

In Perspective, a new session prop was added at session.props.auth.idpAttributes which contains the same JSON object that is returned in the test login response data for OIDC / Ignition IdPs once the user has authenticated to the session (note: SAML does not support and will not set this new session prop). Before the user has authenticated to the session, the JSON object will be empty. Note: in the designer, session.props.auth.idpAttributes is mocked out to be null an empty JSON object since designer sessions do not yet make use of IdPs.

We hope you enjoy these new features. As always, we welcome any feedback or questions you may have.