OpenID Connect Hybrid Flow
On this page
The Hybrid Flow is an OpenID Connect flow which incorporates characteristics of both the Implicit flow and the Authorization Code flow. It enables clients to obtain some tokens straight from the Authorization Endpoint, while still having the possibility to get others from the Token Endpoint.
Authorization Endpoint
-
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
code tokenwas used, then the server returns the authorization code and an access token. - If
code id_tokenwas used, then the server returns the authorization code and an ID token. - If
code id_token tokenwas used, the server returns the authorization code, an ID token and an access token.
- If
Token Endpoint
- The authorization code is sent to the token endpoint, like in the authorization code flow.
- Backend tokens are returned - access token and ID token. If the server settings permit, the refresh token is returned as well.
User Authentication
The user is authenticated during the Authorization flow. This may involve multiple factors and is not defined by neither the OAuth nor the OpenID Connect specifications. In the Curity Identity Server all user authentication is configured in the Authentication Service and is configured per client.
Client Authentication
In the Hybrid Flow, the client is not authenticated to get the tokens from the Authorization Endpoint - the client is identified through the redirect URI, like in the Implicit Flow. To use the Token Endpoint, though, the client must authenticate, as in the Authorization Code flow. Thanks to that the longer lived tokens, like the Refresh Token, can be obtained using this flow.
The Access Token
The Access Token can be returned by both, the Authorization Endpoint and Token Endpoint, depending on the request parameters. These are different tokens, and they can have different properties. For example, the Access Token returned from the Token Endpoint can have a longer lifetime.
The Refresh Token
The Refresh Token is issued if the client is configured to have refresh tokens. 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, it will never be returned from the Authorization Endpoint.
The Authorize Endpoint Request
- Method:
GET - Agent: Browser
- Response Type: Redirect to pre-registered callback at client with parameters in the fragment
Request Parameters
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The Client ID | yes | The ID of the requesting client. |
| response_type | code token orcode id_token orcode id_token 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 | no* | 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 redirect_uri the client wants (4) to redirect to. |
| nonce | a random value | no* | 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 | no* | A challenge generated by the client, if sent, the code_verifier must be sent on the token call. *Required when client must do PKCE (RFC7636). |
| code_challenge_method | “plain” (default) or “S256” | no | Can be used if code_challenge is sent. Defaults to “plain”. Needs to be sent if S256 is used as code_challenge method. |
Response
A redirect back to the redirect_uri. Response parameters are provided 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. |
| access_token | A newly issued access token | no* | The resulting access token for the flow. *Mandatory if access token is requested in the response_type. |
| expires_in | Expiration in seconds | no* | The time to live of the access token in seconds. *Mandatory if access token is requested in the response_type. |
| 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 | no* | Describes how the token can be used. Most commonly Bearer token usage. *Mandatory if access token is requested in the response_type. |
| id_token | JSON Web Token | no* | A JWT representing the ID Token. *Mandatory if ID token is requested in the response_type. |
| code | An Authorization Code | yes | An authorization code nonce, to be used in the token request. |
The Token Endpoint Request
Request Parameters
- Method:
POST - Content-Type:
application/x-www-form-urlencoded - Response Type:
json
| 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 given in the response of 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 representing the ID Token. Present if openid scope was requested and user has given consent to this scope. |
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
