Skip to main content

OpenID Hybrid Flow

Hybrid Flow​

Applications that are able to securely store Client Secrets may benefit from the use of the Hybrid Flow (defined in section 3.3 of the OIDC spec), which allows your application to have immediate access to an ID token while still providing for secure and safe retrieval of access and refresh tokens. This can be useful in situations where your application needs to immediately access information about the user, but must perform some processing before gaining access to protected resources for an extended period of time.

How it works​

Because the Hybrid Flow combines the standard Implicit Flow with Form Post and standard Authorization Code Flow, the steps are similar.

  1. The user clicks Login within the application.
  2. Your application redirects the user to the Haravan Authorization Server (/connect/authorize endpoint) passing along a response_type parameter that indicates the type of requested credential (ID Token and authorization code). It also passes along a response_mode parameter of form_post to ensure security.
  3. Haravan Authorization Server redirects the user to the login and authorization prompt.
  4. The user authenticates using one of the configured login options and may see a consent page listing the permissions Haravan Authorization will give to the application.
  5. Haravan Authorization Server redirects the user back to the application with an authorization code, which is good for one use, plus an ID Token with claims.
  6. Your application sends the code to the Haravan Authorization Server (/connect/token endpoint) along with the application's Client ID and Client Secret.
  7. Haravan Authorization Server verifies the code, Client ID, and Client Secret.
  8. Haravan Authorization Server responds with a second ID Token and Access Token (and optionally, a Refresh Token).
  9. Your application can use the Access Token to call an API to access information about the user and another API.
note

If your application only needs to use Hybrid Flow for sign-on, you will not need a Refresh Token or an Access Token, only an ID Token with claims.

Response type for hybrid flow​

In hybrid flow, we use response_type=code id_token, an authorization code and an ID token are issued from the authorization endpoint, and an access token and an ID token are issued from the token endpoint.

open-id-1

open-id-2

Both the authorization endpoint and the token endpoint issue an ID token, but the contents of the ID tokens are not always the same. ID Token defined in section 3.3.3.6 and section 3.3.2.11 of the OIDC spec

Example of Authorization request.

https://accounts.haravan.com/connect/authorize?response_mode=form_post&response_type=code id_token&scope=openid profile email org userinfo&client_id=YOUR_CLIENT_ID&redirect_uri=https://localhost:3000/login/callback&nonce=FUsh8duTzK6qNbHV

Example of a successful Authorization response for the above request.

POST http://localhost:3000/login/callback
Content-Type: application/x-www-form-urlencoded

code: ADB4CF6799FC6B7C060077BD15C925B507D3A07EF0B1E521D3C185B141314EC9
id_token: eyJhbGciOiJSUzI1NiIsImtpZCI6ImY0ZTExZmMxZjFhOWQyMTRmYzU0M2E0YzExZTkyNDgzIiwidHlwIjoiSldUIn0.eyJuYmYiOjE2MjY3NzQ2OTQsImV4cCI6MTYyNjc3NDk5NCwiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5oYXJhdmFuLmNvbSIsImF1ZCI6ImI2MDM4ZWYxNDdlOTQ2MmNiZjQwMTkyOTc1YWM1YzUwIiwibm9uY2UiOiJGVXNoOGR1VHpLNnFOYkhWIiwiaWF0IjoxNjI2Nzc0Njk0LCJjX2hhc2giOiJVOG1qclZBS1NSRDZ3eW5ZaGRJWGdBIiwic2lkIjoiOTVBMDEyNEUwQUJDNjdFNzAyRDdEMEI1OUM1QkZEOUMiLCJzdWIiOiIyMDAwMDA4MTUwNzEiLCJhdXRoX3RpbWUiOjE2MjY3NzQ2MzEsImlkcCI6ImxvY2FsIiwibG9jYWxlIjoiZW4iLCJvcmdpZCI6IjIwMDAwMDM3NjczNSIsIm1pZGRsZV9uYW1lIjoiTXkgTmFtZSIsIm5hbWUiOiJNeSBOYW1lIiwiZW1haWwiOiJsbWN1b25nMjlAZ21haWwuY29tIiwib3JnbmFtZSI6Ik15IFNob3AiLCJvcmdjYXQiOiJDbG90aGluZyIsImFtciI6WyJwd2QiXSwicm9sZSI6WyJhZG1pbiJdfQ.JTQKFip_N1imekevslOjBp5H3d3G3oJ7-08n0kkov6mq8UfLljnTDMGbpabz8n3ft66GDrsKm71nS0zzXJTbfvPtlfTOzh3UgUxjDxKZJfCeg8pU0SQik6ZY1_hZaidx7ST3IEi7Ac0quKrx6AXtSAEF2kP3cWLfCNvRAWyeZqoE5_hs32XCmUm3vMwJWzwMDN8NjYFM5Icx5xN9STFE1zut4spnPs5wNBWpG0ScjPqUQcf76s8BoP3v-wtnzs3a8aWzLz1bbnhHiNyRnrWfvBtdYJI4voljChTQ_1_AlrMDdWbLeRIUJGX9cE9eHqibvTMfcZvaRDVixw3dtlqH8Q
scope: openid profile email org userinfo

Decrypted ID_token will look like below.

{
  "nbf": 1626774694,
  "exp": 1626774994,
  "iss": "https://accounts.haravan.com",
  "aud": "b6038ef147e9462cbf40192975ac5c50",
  "nonce": "FUsh8duTzK6qNbHV",
  "iat": 1626774694,
  "c_hash": "U8mjrVAKSRD6wynYhdIXgA",
  "sid": "95A0124E0ABC67E702D7D0B59C5BFD9C",
  "sub": "200000815071",
  "auth_time": 1626774631,
  "idp": "local",
  "locale": "en",
  "orgid": "200000376735",
  "middle_name": "My Name",
  "name": "My Name",
  "email": "***@gmail.com",
  "orgname": "My Shop",
  "orgcat": "Clothing",
  "amr": [
    "pwd"
  ],
  "role": [
    "admin"
  ]
}

By sending the code to the token endpoint we can request an access token and id_token.

Here is the curl command for requesting tokens from token endpoint.

curl --location --request POST 'https://accounts.haravan.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'redirect_uri=http://localhost:3000/login/callback' \
--data-urlencode 'code=ADB4CF6799FC6B7C060077BD15C925B507D3A07EF0B1E521D3C185B141314EC9'

Below is the response from token endpoint.

{
    "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImY0ZTExZmMxZjFhOWQyMTRmYzU0M2E0YzExZTkyNDgzIiwidHlwIjoiSldUIn0.eyJuYmYiOjE2MjY3NzQ3MzMsImV4cCI6MTYyNjc3NTAzMywiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5oYXJhdmFuLmNvbSIsImF1ZCI6ImI2MDM4ZWYxNDdlOTQ2MmNiZjQwMTkyOTc1YWM1YzUwIiwibm9uY2UiOiJGVXNoOGR1VHpLNnFOYkhWIiwiaWF0IjoxNjI2Nzc0NzMzLCJhdF9oYXNoIjoiSjhJUlFOR0NTZEltWVF1YTRHSmFGdyIsInNpZCI6Ijk1QTAxMjRFMEFCQzY3RTcwMkQ3RDBCNTlDNUJGRDlDIiwic3ViIjoiMjAwMDAwODE1MDcxIiwiYXV0aF90aW1lIjoxNjI2Nzc0NjMxLCJpZHAiOiJsb2NhbCIsImxvY2FsZSI6ImVuIiwib3JnaWQiOiIyMDAwMDAzNzY3MzUiLCJtaWRkbGVfbmFtZSI6Ik15IE5hbWUiLCJuYW1lIjoiTXkgTmFtZSIsImVtYWlsIjoibG1jdW9uZzI5QGdtYWlsLmNvbSIsIm9yZ25hbWUiOiJNeSBTaG9wIiwib3JnY2F0IjoiQ2xvdGhpbmciLCJhbXIiOlsicHdkIl0sInJvbGUiOlsiYWRtaW4iXX0.dob9Mxi9SpRm2m--1SnA8-tl5exczVaiixEwL5uTQyTMS0w1KPkpP7tw1p9OecDwRDrr56BgCknif5p8He_rNx992VeUAIE2inn49kt8b5UWcicnBtAlpYcnYLD3JmIoAci2JvKMeCrXRHxzjCBdYNfm5stdjmlly0XcXCQCympnNoom0VZDz1nw7WxVWq8daKzjaSgIZHyimHaPQXddbIqPe9Q6mosVUibsG4YE-q1leRDx6ZVuruKm1fYsyKMd0OopVhZJ36FqO2HviwIXkiYdefmikqG4wkbLsuJX48mPbXPBsuWOV4RLGSLGF5PXTfewlEKs3jxNKJ1tyyjy4A",
    "access_token": "0F2C74C4F6F1A3232880A4911CB2AFE558FEB86FC520690E7B9FF3850BB34FB8",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": "openid profile email org userinfo"
}

Decrypted ID_token will be looked like below.

{
  "nbf": 1626774733,
  "exp": 1626775033,
  "iss": "https://accounts.haravan.com",
  "aud": "b6038ef147e9462cbf40192975ac5c50",
  "nonce": "FUsh8duTzK6qNbHV",
  "iat": 1626774733,
  "at_hash": "J8IRQNGCSdImYQua4GJaFw",
  "sid": "95A0124E0ABC67E702D7D0B59C5BFD9C",
  "sub": "200000815071",
  "auth_time": 1626774631,
  "idp": "local",
  "locale": "en",
  "orgid": "200000376735",
  "middle_name": "My Name",
  "name": "My Name",
  "email": "***@gmail.com",
  "orgname": "My Shop",
  "orgcat": "Clothing",
  "amr": [
    "pwd"
  ],
  "role": [
    "admin"
  ]
}

When two id_tokens are issued there are some validations that must be done. In this case one id_token is issued from authorization endpoint and other one is issued from token endpoint. Below are the validations needed from the specification.

  1. "iss" and "sub" claims values must be identical in two id_tokens.
  2. If either ID Token contains claims about the End-User, any that are present in both should have the same values in both.
  3. All Claims about the Authentication event present in either should be present in both.
  4. The at_hash and c_hash Claims may be omitted from the ID Token returned from the Token Endpoint even when these claims are present in the ID Token returned from the Authorization Endpoint.

How to implement it​