OIDC Hybrid Flow

OIDC Hybrid Flow

develop

The OIDC Hybrid Flow in Detail.

Hybrid Flow Overview

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

Implicit Flow

  1. Browser redirects to the Authorize endpoint of the OAuth Server.

  2. If the user isn’t authenticated the OAuth Server redirect to the Authentication Service.

  3. The User authenticates, and is redirected back to the OAuth Server.

  4. The OAuth Server redirects back to the client with appropriate parameters in the response, based on the value of the response_type request parameter:

    • If code token was used, then the server returns the Authentication Code and an Access Token.
    • If code id_token was used, then the server returns the Authentication Code and an ID Token.
    • If code id_token token was used, the server returns the Authentication Code, an ID Token and an Access Token.

Token Endpoint

Implicit Flow

  1. The authorization code is sent to the token endpoint, like in in the Authorization Code flow.
  2. 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 Curity 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

ParameterValueMandatoryDescription
client_idThe Client IDyesThe ID of the requesting client.
response_typecode token / code id_token / code id_token tokenyesDefines the flow type: hybrid flow.
statea random valuenoWill be provided back to the client in (4). Useful to keep track of the session in the client or to prevent unsolicited flows.
scopeSpace separated string of scopesno*List the scopes the client is requesting access to. *Mandatory if ID token is requested in the response_type.
redirect_uriThe client callback URLyesThe redirect_uri the client wants (4) to redirect to.
noncea random valueno*A value that is used to mitigate replay attacks. *Mandatory if ID token is requested in the response_type.
code_challengeA high entropy random challengeno*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”noCan 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.

ParameterValueMandatoryDescription
stateThe same value as given in the requestyes*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_tokenA newly issued access tokenno*The resulting access token for the flow. *Mandatory if access token is requested in the response_type.
expires_inExpiration in secondsno*The time to live of the access token in seconds. *Mandatory if access token is requested in the response_type.
scopeSpace separated stringnoIf not present the requested scopes where issued. If present the issued scopes may differ from the requested scopes.
token_typeBearer or other token typeno*Describes how the token can be used. Most commonly Bearer token usage. *Mandatory if access token is requested in the response_type.
id_tokenJSON Web Tokenno*A JWT representing the ID Token. *Mandatory if ID token is requested in the response_type.
codeAn Authorization CodeyesAn 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
ParameterValueMandatoryDescription
client_idThe Client IDyesThe ID of the requesting client.
client_secretThe client secretyes*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_typeauthorization_codeyesTells the token endpoint to do the second part of the hybrid flow.
codeThe authorization codeyesThe code given in the response of the Authorization request.
redirect_uriThe callback URL of the ClientyesThe same redirect URI as was sent in the authorize request.
code_verifierThe verifier that matches the code_challengeno**Mandatory if code_challenge was used in the authorize request.

Response

  • Response Type: application/json
ParameterValueMandatoryDescription
access_tokenA newly issued access tokenyesThe resulting access token.
refresh_tokenA newly issued refresh tokennoOnly issued if the client is configured to receive refresh tokens.
expires_inExpiration in secondsyesThe time to live of the access token in seconds.
scopeSpace separated stringnoIf not present the requested scopes where issued. If present the issued scopes may differ from the requested scopes.
token_typeBearer or other token typeyesDescribes how the token can be used. Most commonly Bearer token usage.
id_tokenJSON Web TokennoJWT representing the ID Token. Present if openid scope was requested and user has given consent to this scope.

Let’s Stay in Touch!

Get the latest on identity management, API Security and authentication straight to your inbox.

Keep up with our latest articles and how-tos using RSS feeds