Skip to main content

OIDC Overview

Learn about the Open ID Connect (OIDC) extension of the OAuth authorization framework. Get to know what kind of roles are in the framework. Get familiar with the flow concept and see examples.

OpenID Connect in a Nutshell

Open ID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0. It is designed to verify an existing account (identity of an end user) by a third party application using an Identity Provider site (IDP). It complements OAuth 2.0 which is an authorization protocol.

As an authentication result in the authorization flow, the IDP sends the authenticated user's information (details about the login session and the end-user) in a JWT token called an ID token.

The OIDC flow returns not only the ID token but also the access token to ensure compatibility with OAuth 2.0 and support identity authorization scenarios. OpenID Connect purpose is to allow users to only log in once to multiple services/sites. This is made possible via the ID token issued for the client’s consumption, which can be passed around the client's different components as a representation of the successful authentication and the store of user’s profile information. Yet, the ID token should not be used to access APIs. For requesting access to protected resources, you still need to use access tokens. Unlike the ID token, the access token is not intended to carry the user data (except for ID passed as the sub claim) but to transit authorization information, such as scopes determining actions allowed to be taken by the client on the API. Access tokens are for access protected API resources and ID tokens should not be used for API access.

SecureAuth is a certified Open ID provider for a number of use cases, including Financial APIs.

OIDC Flow

The OIDC flow is similar to OAuth 2.0 flow, but the client receives an ID Token in addition to the access token.

OIDC flow

RP: Relying Party OP: OpenID Provider (SecureAuth)

  1. The RP (Client) sends a request to the OP.

  2. The OP authenticates the End-User and obtains authorization.

  3. The OP responds with an ID Token and usually an Access Token.

  4. The RP can send a request with the Access Token to the UserInfo Endpoint.

  5. The UserInfo Endpoint returns Claims about the End-User.

Let's take a deep dive and include a sample IDP, in this case Auth0, in the diagram:

OIDC_Flow.svg

  1. Client app requests the authorization code from SecureAuth.

  2. SecureAuth requests the authorization code from Auth0 IDP.

  3. Auth0 authenticates the user and asks for consent to share data with SecureAuth.

  4. Auth0 issues the code to SecureAuth after user's authentication.

  5. SecureAuth requests tokens from Auth0 using the provided code.

  6. Auth0 issues the tokens to SecureAuth.

  7. Optionally, SecureAuth uses the token to pull additional user information - only when the Get user info option is selected in the connector.

  8. SecureAuth asks for user consent to share data with the client app, unless the client app is marked as trusted or the requested scopes were already granted for this app.

  9. SecureAuth issues the authorization code to the client app.

  10. Client app requests the tokens from SecureAuth.

  11. SecureAuth issues the tokens to the client app. SecureAuth tokens are minted based on the incoming Auth0 tokens with claims mapped to SecureAuth's authentication context.

The following steps in the flow are optional:

  • SecureAuth only pulls user information if this option is explicitly enabled in the Auth0 connector configuration, as explained later in this document.

  • SecureAuth only asks for consent if the client application is not marked as trusted and requests scopes which were not granted previously (or scopes for which the user's consent has been withdrawn).

ID Token

OIDC provides new type of token as an authorization flow result called the ID Token.

ID Token, which is in a JWT format, includes claims with basic user and session information, regarding the authentication of the user.

{
   "iss": "https://server.example.com",
   "sub": "24400320",
   "aud": "s6BhdRkqt3",
   "nonce": "n-0S6_WzA2Mj",
   "exp": 1311281970,
   "iat": 1311280970,
   "auth_time": 1311280969,
   "acr": "urn:mace:incommon:iap:silver"
  }

Required claims:

  • iss: Issuer Identifier for the Issuer of the response.

  • sub: Subject Identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client.

  • aud: Audience(s) that this ID Token is intended for. It MUST contain the OAuth 2.0 client_id.

  • exp: Expiration time on or after which the ID Token MUST NOT be accepted for processing.

  • iat: Time at which the JWT was issued.

Requesting ID Token

In order to obtain the ID Token, the scope scope=openid must be added to the authorization flow request.

An application can ask for more details about user by adding other scope names in the scope parameter.

Scope

Claims

openid

sub, iss, aud, exp, iat,

profile

name, family_name, given_name, middle_name, nickname, picture, and updated_at

email

email, email_verified

Once the user authorized the requested scopes, claims are returned in an ID Token and are also available through the /userinfo endpoint.

OIDC Providers

SecureAuth offers an integration mechanism to integrate your authentication IDP providers, either an OIDC/SAML/Custom one, or built in SecureAuth Identity Pools provider.

OIDC providers supported by SecureAuth with dedicated connection templates include:

  • Auth0

  • AWS Cognito

  • Azure AD

  • Azure B2C

  • Entrust

  • Github

  • Okta

  • Keycloak

You are not limited to those, however, as you can use the Generic OIDC connector to connect any OIDC-compliant provider.

In this section: