OAuth Code Flow

OAuth Code Flow

develop

The OAuth Code Flow Explained

Code Flow Overview

The code flow is the most advanced flow in OAuth. 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 OAuth server and the OAuth server redirects back when done, and the Token flow which is a back-channel call from the Client to the Token endpoint of the OAuth server.

Authorization Endpoint

Code Flow First Part

  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. Note that these two entities, while running in the same product, are separate conceptually.
  3. The User authenticates, and is redirected back to the OAuth Server
  4. The OAuth 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 OAuth 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 Authorization part of the flow. This may involve multiple factors and is not defined by the OAuth specification. In Curity 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

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 for single use. 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 scopesnoList the scopes the client is requesting access to.
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

A redirect back to the “redirect_uri”. Response parameters are provided on the query string.

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
  • 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.

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.
Was this page helpful?