MarketONE OIDC: Introduction

Content

Overview

This topic describes common OpenID Connect (OIDC) workflows as they relate to the MarketONE ULM domain. Although it includes a primer on OIDC, it is not intended as a comprehensive explanation. The OpenID Connect Core 1.0 Specification is the reference specification of the protocol; other specifications also apply to our implementation in the MarketONE ULM domain, and they are linked and referenced below.

Useful Links

OpenID Connect

OpenID Connect is one of the two major protocols supported by the MarketONE ULM domain ULM Identity Provider (IDP). OIDC is an authentication layer which sits on top of the OAuth 2.0 authorization framework. Where OAuth 2.0 allows a User to grant a third party access to protected resources, OIDC extends that to allow the IDP to directly tell the third party information about the User. The pieces of information that the IDP knows about the User are referred to as "claims", and access to those claims is protected through OAuth 2.0 scopes.

The MarketONE ULM domain OIDC implementation is provided by the MITREid Connect Project's OpenID Connect Java Spring Server library. This library builds upon the foundations laid by the Spring Security OAuth library to add OIDC functionality.

Terminology

Although it shares several protocol elements with OAuth 2.0, OIDC defines its own terms for some of the parties involved.

Term Description
End-User The human being granting access to their personal information. The OAuth 2.0 Resource Owner.
Issuer The OpenID Provider which issues the OIDC Access Token, i.e., the IDP. The OAuth 2.0 Authorization Server.
Relying Party (RP) The Third-Party service requesting access to an End-User's personal information using OIDC. The OAuth 2.0 Client.
Subject The End-User.

Major Additions on top of OAuth 2.0

ID Token

In OAuth 2.0, Access Tokens are opaque Strings used to access protected resources. OIDC enhances the OAuth 2.0 IDP response messages with an ID Token, which is a signed JSON Object called a JSON Web Token (JWT). The IDP includes claim data about the Subject within the payload section of the JWT, although not all of the Subject's claims may be included.

UserInfo Endpoint

OIDC adds the UserInfo endpoint, a REST endpoint protected by the OAuth 2.0 Access Token, for the benefit of the Relying Party. When the Relying Party wants the latest version of information contained in the ID Token, or wants access to additional claims to which it was granted access but which may not have been included in the ID Token, it can use its Access Token to query the UserInfo Endpoint for the Subject's claim data.

Claims

OIDC Core defines a number of standard claims in (see ยง5.1 of the OIDC Core specification). A claim is a single key-value pair, where the key is a String and the value is a single JSON "value" (string, number, boolean, array, object).

Common claims include a unique-per-RP identifier for the Subject (claim: sub), various claims representing portions of the Subject's name (given_name, family_name, middle_name, name, nickname, etc.), the Subject's address, phone number, email address, and more.

By default, ULM Core only populates a limited number of these claims. The conversion from ULM User entity into OIDC Claim Set occurs in HibernateUserInfoRepository. Information on how to extend the claim set is discussed below.

OIDC Flows

This section describes common use cases of OIDC endpoints supported by the ULM domain.

Authentication

OIDC modifies the OAuth 2.0 authentication flows (Authorization Code Flow, Implicit Flow, and Hybrid Flow), as well as the use of Refresh tokens, for the new ID Token value.

As with OAuth 2.0, the discriminator selecting which authentication flow is the response_type parameter in the initial request to the Authorization endpoint (/oidc/authorize).

Authorization Code Authentication

In the Authorization Code authentication flow, the Relying Party redirects (HTTP 302) the User's browser to the IDP's own user interface. The User interacts with the IDP's UIs in order to log in (if necessary) and generate a one-time-use Authorization Code; when the interaction is complete, the IDP will redirect (HTTP 302) the User's browser back to the RP with the Authorization Code. Through a back-channel request, the RP then redeems this Authorization Code for the Access Token, ID Token, and optional Refresh Token.

Note: Refer to OIDC Core Section 3.1 for the complete specification of this flow.

Implicit Authentication

The Implicit authentication flow is used when OIDC authentication is to be done "in the background" (e.g., as a web pop-up on top of an interaction with the Relying Party). The RP sends the User's browser to the IDP's own user interface. The User interacts with the IDP's UIs in order to log in (if necessary) and confirm the ID grant to the RP; when the interaction is complete, the IDP will redirect (HTTP 302) the User's browser back to a provisioned endpoint on the RP with the Access Token and/or ID Token values directly in the request.

Note: Refer to OIDC Core Section 3.2 for the complete specification of this flow. The Implicit Authentication flow should be offered if the RP does not have a backend, security is not of the utmost importance, and long live tokens are not required.

Hybrid Authentication

The Hybrid authentication flow is, as the name implies, a hybrid of the Authorization Code and Implicit flows. In the Hybrid flow, either the ID Token or the Access Token is returned directly to the User from the IDP, along with an Authorization Code. The remainder of the ID Token or Access Token which wasn't returned directly, along with the optional Refresh Token, is obtained by the RP using the Authorization Code.

Note: Refer to OIDC Core Section 3.3 for the complete specification of this flow. The Hybrid Authentication flow should be offered if the client needs the token as well, but also when we want to leave the more sensitive data and long lived access to the backchannel only.

Blacklisting / Whitelisting / Approved Sites

The above flow diagrams illustrate the "normal" case when an End-User is authorizing a Relying Party that is neither blacklisted, whitelisted, nor added to the Approved Sites for the User. As described further in the API documentation below, MITREid allows the system to blacklist certain redirect URIs, whitelist certain Relying Parties, or allow Users to "save" their approval for a given site and scopes. The interaction between these three mechanisms at the approval stage is described in the following diagram.

Revision History

Version Description
2020.08 Added this topic.