OpenID Connect (OIDC)

Request flow

1. End User (resource owner) accesses the client application through browser.
2. Client application recognizes that an authenticated client application specific session does not exist and prepares an OpenID connect authentication request in the form of a HTTP POST request. This request will, at minimum, contain– client id, scope(s) – for identity at minimum (OpenID) and redirect URI where it expects authorization server to redirect back in the same browser.
3. Client application issues the redirect request to OpenID Connect Authorization endpoint as prepared in previous step through user agent (browser).
4. Authorization server validates that ClientID received in request is valid/identified (no client authentication at this step), validates the “redirect URI” provided with request is valid/pre-configured, and scope(s) requested by client are not disallowed for it by configuration.
5. In steps 5a and 5b, the Authorization server redirects the end-user to the Identity Provider UI component to obtain the user’s authentication context.
6. Identity Provider UI receives user authentication request from Authorization server. Two things can happen here:
   • If the user-agent (browser) already has an authenticated session for end-user, user doesn’t get prompted for login.
   • If the user-agent (browser) doesn’t have any authenticated session, then Identity Provider UI prompts user for login (enter username and password). Identity Provider UI because of its loosely couple architecture away from authorization server or client application can employ more sophisticated authentication mechanism like two-factor authentication or adaptive authentication.
   Note: After Identity Provider UI has successfully authenticated the user, it creates a secure encrypted payload and redirects back to Authorization Server with user’s authentication context.
7. Authorization server receives user’s authentication information (primary identity like username, complex keys etc.). Further steps depend on what type of “Delegation/User consent” is configured for client application so any of following can happen:
   • Implicit Delegation: If client application is a closely trusted application, then end-user isn’t prompted for any type of user’s authorization and end-user’s permission/authorization is implicitly assumed.
   • Explicit Delegation: If client application is a true third-party application, then end-user is presented with an explicit user consent screen which prompts user to explicitly authorize for the type of permissions (refer to OAuth scope in original client application generated authenticated request in Step# 2). Further narrative assumes that end-user provides at least one type of authorization of all the possible permissions (aka scopes) client application has requested for.
   Note: Even in case of explicit delegation, end-user will not be prompted if he/she has previously in the past has authorized the client application for same or a super-set type of permission unless that past-permission authorization has been explicitly revoked by either administrative or end-user intervention.
8. logoAuthorization Server captures user’s authorization based on previous step and obtains more information about user (if configured, “Get User Attributes connection in picture”) and generates a short-lived authorization code for client application.
9. Authorization Server redirects end-user through user-agent (browser) back to client application and this redirect request is sent to “Redirect URI” as specified by authentication request generated by client application in Step #2. This redirect URI contains authorization code along with it.
10. Client application makes a backchannel (system to system) call to OpenID connect token server. Client application sends following parameters with this request – ClientID, client secret, authorization code – received as a result of Step #9.
    Note: Authorization Server receives the client credentials (ClientID and client secret) and authorization code and validates those (authorization code has very short lifespan). After validation is successful, Authorization Server generates the ID Token (JWT containing user’s identity claims) and an Access Token. ID Token is signed by one of MAC based algorithm using Client Secret to prevent against fraudulent use and maintain integrity of token. ID Token and Access token are returned back to Client application in response.
11. Client application verifies the ID Token (aka JWT) signatures using it’s own “client secret” and using JWS specifications.
    
    • If ID Token validation is successful, client application should create it’s own application specific session and set it in user’s browser to ensure that OpenID Connect request only happens once in a given user’s browser session.
    • If ID Token validation fails, client application should log the error as a security incident and should fail ungracefully without displaying detailed cause about kind of error in user’s browser or in response to prevent against revealing too much information for a potential fraudulent usage.
12. Optionally, in this step, client application may need more identity claims about the user that for security reasons weren’t provided by ID Token validated in Step #11. To achieve that, client application can invoke a User Info endpoint on OpenID Connect Provider and include access token along with this request (It’s implementation specific whether access token will need to be supplied as a request parameter or in Authorization header, it is preferred to have Authorization header with Bearer token). The User Info endpoint will validate the access token and as per configurations will provide/return more identity claims about end-user to client application. After Step #12 which is optional and if not needed, after Step #11 itself – the OpenID Connect specific federated identity exchange process has completed successfully.
    Note: Subsequent steps will dive into how OpenID Connect process also enabled client application receiving an access token that can be used to invoke Business APIs within OpenID connect provider eco-system to fulfill business specific functions which are dependent on business APIs (aka Resource server) – for example, claims, benefits, eligibility etc. API.
13. Assuming Client Application needs to invoke a specific business API to retrieve (or update) more information about end-user to fulfill its business function, client application sends a request to business API. This request can be browser based or server-to-server (there are no restrictions). Client application includes the “access token” received earlier in Step #10 along with this request.
14. Business API (aka Resource Server) invokes the OpenID Connect Token server to validate the access token and also obtain information about end-user identity as well as retrieve user’s authorizations (aka permissions or OAuth scopes) associated with the access token.
    Business API should fail ungracefully if any of the following conditions are occurred as a part of this validation:
    • If access token isn’t valid/not-found/expired.
    • If end-user authorization (aka permissions or OAuth scopes) doesn’t allow or is sufficient to perform the actual API operation invoked by Client Application.
15. Business API after successful validation of access token as well as validation of end-user’s authorization provides response to Client application for its desired API invocation.
16. Client Application now (assuming it doesn’t need to invoke more business APIs immediately) has access to user’s identity, has created its own application session (end result of Step #10/#11) and also has access to resource server (aka API) provided data and continues to engage with user through browser to provide business/UX experience/functions.