OpenID Connect In a Nutshell
Open ID Connect (OIDC) is an authentication protocol built on top of OAuth2.0. It isdesigned toverify an existing account (identity of an end user) by a third party application using an IdentityProvider 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 withOAuth 2.0 and support identity authorization scenarios. OpenID Connect purpose is to allow users toonly log in once to multiple services/sites. This is made possible via the ID token issued for theclient’s consumption, which can be passed around the client’s different components as arepresentation of the successfulauthentication and the store of user’s profile information. Yet, the ID token should not be used to accessAPIs. For requesting access to protected resources, you still need to use access tokens. Unlikethe ID token, the access token is not intended to carry the user data (except for ID passed as thesub claim) but to transit authorization information, such as scopes determining actions allowed tobe taken by the client on the API. Access tokens are for access protected API resources and IDtokens should not be used for API access.
Cloudentity is a certified Open IDprovider for a number of use cases, includingFinancial APIs.
OIDC Flow
The OIDC flow is similar to OAuth 2.0 flow, but the client receives an ID Token in addition tothe access token.
RP: Relying PartyOP: OpenID Provider (Cloudentity)
- The RP (Client) sends a request to the OP.
- The OP authenticates the End-User and obtains authorization.
- The OP responds with an ID Token and usually an Access Token.
- The RP can send a request with the Access Token to the UserInfo Endpoint.
- 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:
sequenceDiagram participant Client app participant Cloudentity participant Auth0 IDP Client app->>Cloudentity: Request authorization code Cloudentity->>Auth0 IDP: Request authorization code Auth0 IDP-->>Auth0 IDP: Authenticate user Auth0 IDP-->>Auth0 IDP: Ask user for consent to share data with Cloudentity Auth0 IDP-->>Cloudentity: Issue authorization code Cloudentity->>Auth0 IDP: Request tokens using the code Auth0 IDP-->>Cloudentity: Issue tokens opt Cloudentity->>Auth0 IDP: Pull user information Auth0 IDP-->>Cloudentity: Return user data end opt Cloudentity-->>Cloudentity: Ask user for consent to share data with client app end Cloudentity-->>Client app: Issue authorization code Client app->>Cloudentity: Request tokens using the code Cloudentity-->>Client app: Issue tokens requested by the app
Client app requests the authorization code from Cloudentity.
Cloudentity requests the authorization code from Auth0 IDP.
Auth0 authenticates the user and asks for consent to share data with Cloudentity.
Auth0 issues the code to Cloudentity after user’s authentication.
Cloudentity requests tokens from Auth0 using the provided code.
Auth0 issues the tokens to Cloudentity.
Optionally, Cloudentity uses the token to pull additional user information - onlywhen the Get user info option is selected in the connector.
Cloudentity asks for user consent to share data with the client app, unless theclient app is marked as trusted or the requested scopes were already granted for this app.
Cloudentity issues the authorization code to the client app.
Client app requests the tokens from Cloudentity.
Cloudentity issues the tokens to the client app. Cloudentity tokensare minted based on the incoming Auth0 tokens with claims mapped to Cloudentity’sauthentication context.
The following steps in the flow are optional:
- Cloudentity only pulls user information if this option is explicitlyenabled in the Auth0 connector configuration, as explained later in this document.
- Cloudentity only asks for consent if the client application is not marked astrusted and requests scopes which were not granted previously (or scopes for which the user’s consenthas 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 forthe 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.0client_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_verified |
Once the user authorized the requested scopes, claims are returned in an ID Token and are alsoavailable through the /userinfo endpoint.
OIDC Providers
Cloudentity offers an integration mechanism to integrate your authentication IDPproviders, either an OIDC/SAML/Custom one, or built in Cloudentity Identity Pools provider.
OIDC providers supported by Cloudentity 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 OIDCconnector to connect anyOIDC-compliant provider.
