OpenID Connect Code Flow

OpenID Connect Code Flow

The Authorization Code Flow is the most advanced flow in OpenID Connect. It is also the most flexible, that allows both mobile and web clients to obtain tokens securely. It is split into two parts, the authorization flow that runs in the browser where the client redirects to the OpenID Provider (OP) and the OP redirects back when done, and the token flow which is a back-channel call from the client to the token endpoint of the OP.

Authorization Endpoint

Code Flow First Part

  1. Browser redirects to the Authorize endpoint of the Authorization Server
  2. If the user isn't authenticated the Authorization Server redirect to the Authentication Service. Note that these two entities, while running in the same product, are separate conceptually.
  3. The User authenticates, and is redirected back to the Authorization Server
  4. The Authorization Server issues a one time token called an Authorization Code

Token Endpoint

Code Flow Second Part

  1. The Client backend makes a POST request to the Token endpoint with the Authorization Code and Client Credentials
  2. The Authorization Server validates the code and the credentials, and returns an access token and optionally a refresh token if configured on the client.

User Authentication

The user is authenticated during the a part of the flow. This may involve multiple factors and is not defined by the specification. In the Curity Identity Server all user authentication is configured in the Authentication Service and is configured per client.

Client Authentication

The client authenticates in the Token part of the flow. Client authentication can be done in many ways, the most common being client secret. The following authentication mechanisms are supported in Curity:

  • No authentication (public client)
  • Secret in post body
  • Secret using basic Authentication
  • Client Assertion JWT
  • Mutual TLS (mTLS) client certificate
  • Asymmetric Key
  • Symmetric Key
  • Credential Manager
  • JWKS URI

The Authorization Code

Once the authorization flow is done, the redirect back to the client contains an authorization code. This is a nonce, not-more-than-once token, that is to be used a single time. It has a short lifespan (usually less than 30 seconds) and must be presented in the token part of the flow.

The Access Token

The Access Token is returned by the token endpoint. It is the token that later can be used to call the API and gain access. It is a Bearer token, and must not be sent to untrusted parties. The access token usually have a lifetime of 5-30 minutes.

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 Authorization Endpoint Request

  • Method: GET
  • Agent: Browser
  • Response Type: Redirect to pre-registered callback at client with query parameters

Request Parameters

ParameterValueMandatoryDescription
client_idThe Client IDyesThe ID of the requesting client
response_typecodeyesDefines the flow type: authorization code 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 scopesyesList the scopes the client is requesting access to. OpenID Connect requests MUST contain the openid scope.
redirect_uriThe client callback URLno*The redirect_uri the client wants (4) to redirect to. *Mandatory if multiple redirect URIs are configured on the client.
code_challengeA high entropy random challengeno*A challenge generated by the client, if sent, the code_verfier 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_modeString defining the response modenoInforms the Authorization Server how to return the Authorization Response parameters. Possible values are query or fragment. The draft extension — JWT Secured Authorization Response Mode for OAuth 2.0 defines additional response modes, query.jwt, fragment.jwt, form_post.jwt or jwt.
nonceA random valuenoA String value used to mitigate replay attacks by associating the client session with the ID token.
display"page", "popup", "touch" or "wap"noString specifying how user authentication and consent screens are presented to the end user.
prompt"none", "login", "consent" or "select_account"noSpace separated string specifying user prompts for reauthentication and consent.
max_ageAllowable elapsed time in secondsnoIf the elapsed time since user authentication is greater than this value the Authorization Server will re-authenticate the user.
ui_localesSpace separated list of language tag valuesnoThe preferred languages of the end user interface. A list of language tag values in a prioritized order. Ex. sv en ge
id_token_hintAn ID tokennoA previous ID token passed as a hint about the user's past or current authenticated sessions. If the user is already logged in or being logged in by the request, the Authorization Server returns a positive response. Otherwise, an error is returned.
login_hintUser’s login identifiernoHint passed to the Authorization Server about the identifier the user is logging in with. This can be used if the Relaying Party first asks for the user identifier (ex. email or phone number).
acr_valuesRequested acr valuesnoSpace separated string of requested Authentication Context Class Reference (ACR) values in order of preference.
claims_localesSpace separated list of language tag valuesnoThe user's preferred language of returned claims. A list of language tag values in a prioritized order. Ex. sv en ge
claimsA JSON object listing the requested claimsnoList the claims the client is requesting.
requestA Request ObjectnoThe parameter enables the request to be passed as a Request Object. The Request Object is an optionally signed and/or encrypted JWT where the claims are the request parameters.
request_uriA URL using the https schemenoAllows the request to be passed as a reference instead of by value (request). The value is a URL referencing a or the Request Object that is a JWT containing the request parameters as claims.

Additional Authorization Request Parameters

Additional authorization request parameters can be found in this Internet Assigned Numbers Authority (IANA) listing. Sort by Parameter Usage Location column and find the parameters by authorization request.

Response

A redirect back to the “redirect_uri”. Response parameters are provided on the query string by default or as defined by the response_mode in the request.

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
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
  • Agent: HTTP client
  • 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
grant_typeauthorization_codeyesTells the token endpoint to do the second part of the code flow.
codeThe authorization codeyesThe code given in the response of the Authorization request
redirect_uriThe callback URL of the Clientno*The same redirect URI as was sent in the authorize request. *Required if redirect_uri was sent in the authorize request.
code_verifierThe verifier that matches the code_challengeno**Mandatory if code_challenge was used in the authorize request.

Additional Token Request Parameters

Additional token request parameters can be found in this Internet Assigned Numbers Authority (IANA) listing. Sort by Parameter Usage Location column and find the parameters by token request.

Response

  • Response Type: application/json
ParameterValueMandatoryDescription
access_tokenA newly issued access tokenyesThe resulting access token for the code flow
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_tokenA newly issued ID tokenyesThe resulting ID token for the code flow.

Additional Token Response Parameters

Additional token response parameters can be found in this Internet Assigned Numbers Authority (IANA) listing. Sort by Parameter Usage Location column and find the parameters by token response.