Hybrid Flow

Overview

The Hybrid Flow in OpenID Connect (OIDC) combines the benefits of the Authorization Code Flow and the Implicit Flow. It allows applications to immediately receive an ID token while providing the option to obtain an authorization code that can be exchanged for access tokens, refresh tokens, and more. This flow is ideal for use cases where an immediate ID token is required for user authentication, but the application also needs long-lived access through refresh tokens. It is suitable for scenarios where applications combine public and confidential client functionalities.

• Ideal for scenarios requiring instant ID token access while maintaining long-lived sessions using refresh tokens.
• Ideal for applications that blend both client-side and server-side functionalities."

• Allows retrieval of both tokens and an authorization code in a single round trip.
• Supports refresh tokens and long-lived sessions.
• Requires a backend to store secrets securely.

1. Initiate Authorization Request Redirect the user to the authorization endpoint:

https://<siteurl>/service/oidc/{OIDCAppName}/authorize?client_id={OIDC Client ID}&redirect_uri={Callback URL}&scope=openid&response_type={response_type}&state={random string}&nonce={unique nonce}

• Query Parameters:
  • client_id: OIDC client ID.
  • redirect_uri: Callback URL.
  • response_type: Can be code token, code id_token, or code token id_token.
  • state: Random string for CSRF protection.
  • scope: Must include openid with optional additional scopes.
  • nonce: Unique value for replay protection.

2. Receive Tokens and/or Authorization Code Based on the response_type, the following will be returned in the redirect URI:

   • response_type=code token:

REDIRECT_URI?code={authorization code}&token={access_token}&state={state}

• response_type=code id_token:

REDIRECT_URI?code={authorization code}&id_token={JWT token}&state={state}

• response_type=code token id_token:

REDIRECT_URI?code={authorization code}&token={access_token}&id_token={JWT token}&state={state}

3. Exchange Authorization Code (Optional) If an authorization code is received, exchange it for tokens via the token endpoint:

POST https://<siteurl>/api/oidc/{oidcAppName}/token

• Request Body:

{
  "client_id": "<OIDC Client ID>",
  "client_secret": "<Client Secret>",
  "redirect_uri": "<Callback URL>",
  "grant_type": "authorization_code",
  "code": "<authorization code>"
}

• Response:

{
  "access_token": "<token>",
  "id_token": "<id token>",
  "refresh_token": "<refresh token>",
  "expires_in": <seconds>
}

Below are the Supported Scops and its claims:

Scope	Claim Name	LoginRadius Profile Field
email	email	Email.Value
	email_verified	EmailVerified
phone	phone_number	PhoneId
	phone_number_verified	PhoneVerified
profile	name	FullName
	family_name	LastName
	given_name	FirstName
	middle_name	MiddleName
	nickname	NickName
	preferred_username	UserName
	profile	Profileurl
	picture	GravatarImageUrl
	website	Website
	gender	Gender
	birthdate	BirthDate
	zoneinfo	TimeZone
	locale	LocalLanguage
	updated_at	ModifiedDate
address	street_address	Addresses.Address1
	locality	Addresses.City
	region	Addresses.Region
	postal_code	Addresses.PostalCode
	country	Addresses.Country

Scopes are passed in the Authorization Request as a query string; for the openID flow, it's required to pass the openid scope; we can pass the multiple scopes separated by space, for example:

https://<siteurl>/service/oidc/{OIDCAppName}/authorize?scope=openid%20email&client_id=94fa4f2xxxxxxxxxxxxf4124753841bd&redirect_uri=https://example.com&response_type=code&state=7d3dfb2dfgdfgdfdfdf

The Hybrid Flow offers a flexible solution for applications requiring immediate user authentication via an ID token and long-lived access through authorization codes and refresh tokens. By leveraging this flow, developers can balance security and user experience, seamlessly handling public and confidential client functionalities. It provides robust support for modern applications needing scalable and secure authentication in OpenID Connect.