Overview #

Authorization Code Flow is the OAuth 2.0 Protocol Flow for the Authorization Code Grant Type which would typically be used for website type applications.

Authorization Code Flow is also called 3-legged OAuth and is a relatively high Level Of Assurance.

OAuth 2.0 Security Best Current Practice #

states:
Clients utilizing the authorization grant type MUST use PKCE RFC 7636 in order to (with the help of the Authorization Server) detect and prevent attempts to inject (replay) Authorization Codes into the Authorization Response. The PKCE challenges must be transaction-specific and securely bound to the user agent in which the transaction was started and the respective client. OpenID Connect clients MAY use the nonce parameter of the OpenID Connect Authentication Request as specified in OpenID in conjunction with the corresponding ID Token claim for the same purpose.

Clients SHOULD use PKCE Code_challenge_methods that do not expose the PKCE Code_verifier in the Authorization Request. (Otherwise, the attacker A4 can trivially break the security provided by PKCE.) Currently, S256 is the only such method.

AS MUST support PKCE RFC 7636.

AS SHOULD provide a way to detect their support for PKCE. To this end, they SHOULD either (a) publish, in their AS metadata (RFC 8414), the element code_challenge_methods_supported containing the supported PKCE [Code_challenge_methods]] (which can be used by the client to detect PKCE support) or (b) provide a deployment-specific way to ensure or determine PKCE support by the AS.

Authorization Servers SHOULD furthermore consider the recommendations given in RFC 6819, Section 4.4.1.1, on authorization code replay prevention.

The Flow#

The authorization Code Grant type is used to obtain both access_tokens and refresh_tokens and is optimized for OAuth Confidential Clients. Since this is a redirection-based flow, the OAuth Client must be capable of interacting with the Resource Owner's user-agent (typically a web browser) and capable of receiving incoming requests (via URL redirection) from the Authorization Server.

 
+----------+ 
| Resource | 
| Owner | 
| | 
+----------+ 
^ 
| 
(B) 
+----|-----+ Client Identifier +---------------+ 
| -+----(A)-- & Redirection URI ---->| | 
| User- | | Authorization | 
| Agent -+----(B)-- User authenticates --->| Server | 
| | | | 
| -+----(C)-- Authorization Code ---<| | 
+-|----|---+ +---------------+ 
| | ^ v 
(A) (C) | | 
| | | | 
^ v | | 
+---------+ | | 
| |>---(D)-- Authorization Code ---------' | 
| Client | & Redirection URI | 
| | | 
| |<---(E)----- Access Token -------------------' 
+---------+ (w/ Optional Refresh Token) 
Figure 3: Authorization Code Flow 

Note: The lines illustrating steps (A), (B), and (C) are broken into two parts as they pass through the user-agent.

Known in Advance #

Some basic conditions must exist in advance:

• The OAuth Client MUST be aware of the correct Authorization Server associated with the Resource Server
• The OAuth Client MUST have registered with the correct Authorization Server and provided them with his:
  • Client_id
  • Client Secret
  • Redirect URI
• The OAuth Client MUST know the Authorization_endpoint.
• The specifications do not indicate any communication between the Authorization Server associated with the Resource Server.

Many Authorization Servers and most OpenID Connect Providers support Openid-configuration Discovery Mechanism

The flow illustrated in Figure 3 includes the following steps:

(A) Authorization Request #

The OAuth Client initiates the flow by directing the user-agent to the Authorization_endpoint with an Authorization Request wihich includes:

• client_id
• OAuth Scope
• state
• Redirect_uri which the Authorization Server will send the user-agent back once access is granted (or denied).

(B) Authorization Grant #

The Authorization Server authenticates the Resource Owner (via the user-agent) (Authentication Method is undefined in OAuth 2.0) and establishes whether the Resource Owner grants or denies the OAuth Client's Authorization Request.

(C) Authorization Response #

Assuming the Resource Owner grants access, the Authorization Server redirects the user-agent back to the OAuth Client using the redirect URI provided in the Authorization Request earlier (or the during OAuth 2.0 Client Registration. The URL redirection URI includes an Authorization Code and any local state provided by the OAuth Client earlier. The OAuth Client MUST validate that the OAuth state parameter value returned in the Authorization Response is identical to the value sent in the Authorization Request

(D) OAuth Token Request #

The OAuth Client requests an Access Token from the Authorization Server's token_endpoint by including the Authorization Code received in the previous step. When making the request, the OAuth Client authenticates with the Authorization Server. The OAuth Client includes the redirect URI used to obtain the Authorization Code for verification.

(E) OAuth Token Response #

The Authorization Server:

• authenticates the OAuth Client
• validates the Authorization Code
• ensures that the redirect URI received matches the URI used to redirect the OAuth Client in step (C).

If validation is successful, the Authorization Server responds back with:

• Access Token
• Refresh Token (Optional)
• and (IF) OpenID Connect Id_token

OAuth Client Validations#

• Access Token Validation
• Identity Token Validation
• OAuth Scope Validation

Access Resources#

The OAuth Client can now use the Access Token to request resources from the Resource Server. The Access Token serves as both:

• Authentication of the OAuth Client
• Authorization by the Resource Owner (user) to to access the Resource Server.
• OpenID Connect the Access Token can be used to access the Userinfo_endpoint:
  • UserInfo Request
  • UserInfo Response

Best Practices OpenID Connect#

Please always follow the Best Practices OpenID Connect

More Information #

There might be more information for this subject on one of the following:

• Authorization Code
• Authorization Code Grant
• Grant Types
• Hybrid Flow
• Id_token_signing_alg_values_supported
• Identity Token
• OAuth 2.0 Protocol Flows
• OAuth Dynamic Client Registration Metadata
• OpenID Connect Authentication Response
• OpenID Connect Authorization Flow
• Proof Key for Code Exchange by OAuth Public Clients
• Token_endpoint

---

• [#1] - RFC 6749 - based on data observed:2015-05-18