OpenID Connect Authorization Code Flow
On this page
What is the OpenID Connect Authorization 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
- 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. Note that these two entities, while running in the same product, are separate conceptually.
- The User authenticates, and is redirected back to the Token Service.
- The Authorization Server issues a one time token called the authorization code.
Token Endpoint
- The client backend makes a POST request to the token endpoint with the authorization code and client credentials.
- The Authorization Server validates the code and the credentials. It returns an access token and optionally a refresh token if configured.
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
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The Client ID | yes | The ID of the requesting client |
| response_type | code | yes | Defines the flow type: authorization code 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 | yes | List the scopes the client is requesting access to. OpenID Connect requests MUST contain the openid scope. |
| redirect_uri | The client callback URL | no* | The redirect_uri the client wants (4) to redirect to. *Mandatory if multiple redirect URIs are configured on the client. |
| code_challenge | A high entropy random challenge | no* | 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” | 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_mode | String defining the response mode | no | Informs 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. |
| nonce | A random value | no | A String value used to mitigate replay attacks by associating the client session with the ID token. |
| display | "page", "popup", "touch" or "wap" | no | String specifying how user authentication and consent screens are presented to the end user. |
| prompt | "none", "login", "consent" or "select_account" | no | Space separated string specifying user prompts for reauthentication and consent. |
| max_age | Allowable elapsed time in seconds | no | If the elapsed time since user authentication is greater than this value the Authorization Server will re-authenticate the user. |
| ui_locales | Space separated list of language tag values | no | The preferred languages of the end user interface. A list of language tag values in a prioritized order. Ex. sv en ge |
| id_token_hint | An ID token | no | A 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_hint | User’s login identifier | no | Hint 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_values | Requested acr values | no | Space separated string of requested Authentication Context Class Reference (ACR) values in order of preference. |
| claims_locales | Space separated list of language tag values | no | The user's preferred language of returned claims. A list of language tag values in a prioritized order. Ex. sv en ge |
| claims | A JSON object listing the requested claims | no | List the claims the client is requesting. |
| request | A Request Object | no | The 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_uri | A URL using the https scheme | no | Allows 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.
| 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 |
| iss | Issuer Identifier | yes* | 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 |
| 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 - Agent:
HTTP client - 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 |
| grant_type | authorization_code | yes | Tells the token endpoint to do the second part of the code flow. |
| code | The authorization code | yes | The code given in the response of the Authorization request |
| redirect_uri | The callback URL of the Client | no* | The same redirect URI as was sent in the authorize request. *Required if redirect_uri 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. |
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
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| access_token | A newly issued access token | yes | The resulting access token for the code flow |
| 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 | A newly issued ID token | yes | The 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.
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
