OpenID Connect Hybrid Flow
On this page
The hybrid flow is an OpenID Connect flow that incorporates characteristics of both the implicit flow and the authorization code flow. It enables clients to obtain ID tokens straight from the authorization endpoint (via front-channel), while still being able to obtain access and refresh tokens from the token endpoint (via back-channel). This makes the hybrid flow particularly suitable for applications needing a balance between security and responsiveness.
This article explains the main components of the hybrid flow and how it combines the implicit flow for the ID token with the authorization code flow for the access token.
Best Practices
The OAuth implicit flow is deprecated. As a result, do not include the string token in the response_type request parameter. Only use code id_token for the hybrid flow. If possible, rely on the code flow to retrieve all tokens
How the OIDC Hybrid Flow Works
Authorization Request and Response
-
The browser redirects to the authorization endpoint at the token service of the authorization server.
-
If the user is not yet authenticated, the token service redirects to the authentication service.
-
The user authenticates and is redirected back to the token service.
-
The authorization server redirects back to the client with appropriate parameters in the response, based on the value of the
response_typerequest parameter:- If the client used
code id_token, then the server returns the authorization code and an ID token.
- If the client used
Token Request and Response
- The client sends the authorization code to the token endpoint, like in the authorization code flow.
- The authorization server returns tokens, typically including the access token and the ID token. If the server settings permit, the authorization server also issues a refresh token.
User Authentication
The user is authenticated during the authorization flow. Neither the OAuth nor the OpenID Connect specifications define the particulars for user authentication. It may thus involve any authentication method or multiple factors. Modern authorization servers apply conditional authentication, which adapts the flow depending on the context. In the Curity Identity Server, all user authentication is configured in the Authentication Service ensuring fine-grained control over authentication policies.
Client Authentication
In the hybrid flow, the client is not authenticated when calling the authorization endpoint but is identified through the redirect URI. The client must authenticate at the token endpoint, though, just like in the authorization code flow. Thanks to that, the client can obtain access tokens and longer-lived refresh tokens using the back-channel during the hybrid flow.
The Access Token
The authorization server should not return any access tokens through the front-channel (i.e., as part of the browser redirect). Instead, the client should fetch access tokens in a back-channel request from the token endpoint. The authorization server may return a refresh token as well.
The Curity Identity Server supports returning access tokens in the front-channel. However, such tokens are limited in terms of scope, lifetime, and audience to mitigate security risks. For the same reason, the Curity Identity Server does not return refresh tokens in the front-channel.
The Refresh Token
The authorization server can, depending on its policies, return refresh tokens to the client. This token can be used to obtain more access tokens once the first one expires. The refresh token may have a very long lifetime, ranging from hours to years.
The refresh token can only be obtained from the token endpoint; the Curity Identity Server will never return it from the authorization endpoint.
The Authorization Request
- Method:
GET - Agent: Browser
- Response Type: Redirect to pre-registered callback URI at client with parameters in the fragment
The following table outlines the parameters for the front-channel communication in the hybrid flow.
Request Parameters
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The client ID | yes | The ID of the requesting client. |
| response_type | code id_token* | yes | Defines the flow type: hybrid flow. |
| state | A random value | no | Will be provided back to the client in (4). Useful to keep track of the session in the client or to prevent unsolicited flows. |
| scope | Space-separated string of scopes | yes* | List the scopes the client is requesting access to. *Mandatory if ID token is requested in the response_type. |
| redirect_uri | The client callback URL | yes | The URI that the client wants the authorization response in step (4) to redirect to. |
| nonce | A random value | yes* | A value that is used to mitigate replay attacks. *Mandatory if ID token is requested in the response_type. |
| code_challenge | A high entropy random challenge | yes* | A challenge generated by the client, if sent, the code_verifier must be sent on the token call. *Part of PKCE (RFC 7636), recommended. |
| code_challenge_method | SHA256 | yes* | The hash method to validate the PKCE (RFC 7636) flow. *Should be S256 and is then required if code_challenge method is included. |
Response
The authorization server creates a redirect back to the redirect_uri. It provides the response parameters on the fragment part of the URL. This means that
only the browser can access the values of the response. The client server will not receive these values.
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| state | The same value as given in the request | yes* | The same value as the client sent in the request. Use to match request to the redirect response. *Mandatory if the state was sent in the request. |
| code | An Authorization Code | yes | An authorization code, to be used in the token request. |
| id_token | JSON Web Token | yes* | A JWT representing the ID token. *Mandatory if the ID token is requested in the response_type. |
The Token Request
Request Parameters
- Method:
POST - Content-Type:
application/x-www-form-urlencoded - Response Type:
json
This represents the back-channel token exchange, providing enhanced confidentiality for sensitive tokens.
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The client ID | yes | The ID of the requesting client. |
| client_secret | The client secret | yes* | The secret of the client. *Mandatory if client authentication is of type secret and the authentication is not done using basic authentication. Other methods of client authentication may require different parameters sent in the request. |
| grant_type | authorization_code | yes | Tells the token endpoint to do the second part of the hybrid flow. |
| code | The authorization code | yes | The code is given in the response to the authorization request. |
| redirect_uri | The callback URL of the Client | yes | The same redirect URI as was sent in the authorize request. |
| code_verifier | The verifier that matches the code_challenge | no* | *Mandatory if code_challenge was used in the authorize request. |
Response
- Response Type:
application/json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| access_token | A newly issued access token | yes | The resulting access token. |
| refresh_token | A newly issued refresh token | no | Only issued if the client is configured to receive refresh tokens. |
| expires_in | Expiration in seconds | yes | The time to live of the access token in seconds. |
| scope | Space-separated string | no | If not present, the requested scopes where issued. If present, the issued scopes may differ from the requested scopes. |
| token_type | Bearer or other token type | yes | Describes how the token can be used. Most commonly bearer token usage. |
| id_token | JSON Web Token | no | JWT represents the ID token. Present if openid scope was requested and the user has given consent to this scope. |
Key Takeaways
The OpenID Connect hybrid flow provides a flexible and secure mechanism for handling authentication and authorization in modern web and mobile applications. By combining features of the implicit and authorization code flows, it allows clients to receive tokens both immediately and through secure exchanges, ensuring an optimal balance of user experience and security. It is particularly valuable when applications require both immediate access and long-term session management through refresh tokens.
Michał Trojanowski
Product Marketing Engineer at Curity
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
