The OAuth authorization code flow explained.

OAuth Code Flow

On this page

OAuth Authorization Code Flow Explained

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 and gain access to web APIs. 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.

OAuth Code Flow Example

Authorization Endpoint

Code flow diagram first part
  1. Browser redirects to the authorization endpoint at the Token Service of the Authorization Server.
  2. If the user is not yet authenticated, the Token Service redirects 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 Token Service.
  4. The Authorization Server issues a one time token called the authorization code.

Token Endpoint

Code flow diagram 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. It returns an access token and optionally a refresh token if configured.

How the Code Flow Works

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

Additional Request Parameters

For additional request parameters refer to the OpenID Connect Authorization Code Flow.

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
issIssuer Identifieryes*The issuer identifier of the authorization server where the authorization request was sent to. *Mandatory if the authorization server supports the OAuth 2.0 Authorization Server Issuer Identifier specification
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.

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.

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