OIDC Hybrid flow usage example

Use Case Scenario

This use case demonstrates the different steps required to execute an OIDC hybrid flow with user interactions.

Since the OIDC hybrid flow extends the authorization code flow, this example is very similar to Authorization code flow usage.

Prerequisites

The OIDC hybrid flow is set up in the authorization server (here IAM) and the relying party is already registered through dynamic client registration (client credentials grant usage example) or configured as a static client in the configuration (Configuration of IAM as OAuth Authorization Server / OpenID Provider

Overview of Steps

A relying party (client) starts an authorization code flow (authorize call). Requesting an additional ID and/or access token indicates to the AS that hybrid flow should be used.
The user is authenticated and agrees to the consent request.
The client receives the authorization code. Because we are in a hybrid flow, the response also contains an ID token and/or access token.
The client may now inspect and use the ID and/or access token.
The client sends the authorization code to the AS and exchanges it for ID, access, and refresh tokens. Note that these ID and access tokens are not the same as the ones above.

Step 1 – Start the OIDC Hybrid Flow

To start the hybrid code flow, open a browser window and enter the following URL:

Example URL to start a hybrid flow:

https://oidc.airlock.com/auth-login/oauth2/v3/myAS/authorize?
    response_type=code+id_token+token    &redirect_uri=https://oidc.airlock.com/application/demo
    &client_id=oidc-client
    &state=ee26b0dd4a...28a8ff
    &nonce=n-0S6_WzA2Mj 
    &scope=employee%20openid

To successfully start a hybrid flow, the following conditions must be met:
The response_type must include the id_token and/or token part. It tells the AS to send back an additional ID and/or access token. If neither of the two is specified, an OIDC authorization code flow is started instead. Note that the nonce parameter is mandatory if an ID token is requested.
A valid redirect_uri must be present in the request.
The redirect_uri must be on the list of redirect_uris registered during client registration.
A client_id must be present.
The scope openid must be present.
One additional scope must be present, if the authorization server has required scopes configured.
The redirect_url must be URL encoded.

If one of the conditions is not met, the authorization server returns an error message.

Submitting the state parameter is not required by the standard, but it is strongly recommended to protect against CSRF.

Step 2 – Authentication and Consent

Airlock IAM will present a login screen:

... and optionally ask for consent:

Step 3 – Retrieve Authorization Code

If both authentication and consent grants have succeeded, Airlock IAM redirects the browser to the redirect_uri requested in Step 1.

Redirect URL after starting hybrid code flow and authentication

https://oidc.airlock.com/application/demo#     code=xRbH9uoaMMWB6urmWsg8b1xwJQF~JfD2s9CoUvwVWX42YxBwqfeC2RVWeG1HkvkdtxHz
     &id_token=eyJ0...Zxo
     &access_token=YL3x...ytP
     &token_type=bearer
     &expires_in=1234
     &state=ee26b0dd4a...28a8ff

Compared to the OIDC authorization code flow, an additional ID token and access token are sent to the browser directly with the authorization code.

The code and the tokens are passed as a fragment rather than a query string (using # instead of ? in the URL). This is because the ID and access tokens are meant to be extracted by the web browser (or mobile app) and should not be sent to the RP (client).

Using a fragment (#) is the default behavior.

The Airlock IAM configuration allows changing the default to send the tokens and the code as query or form post parameters. This may be required user agent or the relying party.

See Advanced Settings in the hybrid flow configuration for further information.

The browser (or mobile app) may now examine and use the ID and access token and then sends the authorization code to the RP (client).

Step 4 – Obtain ID, Access, and Refresh Tokens

The relying party (client) receives the authorization code and sends it to the AS to get the ID, access, and refresh tokens. Note that the following request is not sent by the browser but by the relying party.

Token endpoint request

https://oidc.airlock.com/auth-login/rest/oauth2/authorization-servers/myAS/token

Content-Type: application/x-www-form-urlencoded
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ
grant_type=authorization_code
code=xRbH9uoaMMWB6urmWsg8b1xwJQF~JfD2s9CoUvwVWX42YxBwqfeC2RVWeG1HkvkdtxHz
redirect_uri=https://oidc.airlock.com/application/demo

It is recommended to configure the authorization server, to enforce authentication on the token endpoint.

The authorization server will respond as follows:

Code Block token endpoint response

200 OK
 {
    "access_token": "eyJraWQiOiI3YWRmMz...E9nfs7YyJZdRFP",
    "scope": "email",
    "id_token": "eyJraWQiOiI3YWRmMzgp74...Ex86vUkyMGqxQg",
    "token_type": "bearer",
    "expires_in": 17999
 }