OAuth 2.0 Authorization Code Flow

What is OAuth 2.0?

OAuth 2.0 is an authorization framework, not an authentication protocol. It enables applications (called Clients) to obtain limited access to user accounts on an HTTP service, such as Google, GitHub, or Facebook. It delegates authorization from the Resource Owner (the user) to the Client application, with the approval orchestrated by an Authorization Server. The Client then uses the granted access (an Access Token) to request protected resources from a Resource Server.

Why Use OAuth 2.0?

• Security: The user never shares their primary credentials (like their Google password) directly with the Client application.
• Limited Access (Scopes): The Client requests specific permissions (called scopes, e.g., "read contacts", "post tweet"), and the user can approve or deny these specific permissions.
• User Control: The user explicitly grants consent for the Client to access their data and can typically revoke this access later via the Authorization Server's settings.

Key Roles in OAuth 2.0

• Resource Owner: You, the end-user who owns the data.
• Client: The application (e.g., a website, mobile app) wanting to access your data on your behalf. It needs a unique Client ID and sometimes a Client Secret.
• Authorization Server: The server that authenticates the Resource Owner, receives their consent, and issues access tokens (e.g., google.com, github.com).
• Resource Server: The server hosting the protected resources (e.g., Google Contacts API, GitHub API). It accepts and validates access tokens.

*(Often, the Authorization Server and Resource Server are part of the same overall service, like Google handling both authentication/token issuing and the GMail API).*

The Authorization Code Flow (for Web Apps)

This is the most common and secure flow for web applications where the Client has a backend component.

+--------+                                           +---------------+
|        |--(A)------- Authorization Request ------>|               |
|        |       Redirect User-Agent w/ Consent    | Authorization |
|        |<-(B)-- Authorization Code Grant --------|     Server    |
| Client |                                         +---------------+
|        |                               +-----------------+
|        |--(C)-- Authorization Code --->|                 |
|        |      w/ Client Credentials    | Authorization |
|        |<-(D)----- Access Token -------|     Server    | Token Endpoint
|        |    (Optional Refresh Token)   +-----------------+
|        |
|        |                               +-----------------+
|        |--(E)----- Access Token ------>|                 |
|        |      Requesting Resource      | Resource Server |
|        |<-(F)--- Protected Resource ---|                 |
+--------+                               +-----------------+
        

1. Authorization Request (A): The Client redirects the Resource Owner's browser to the Authorization Server's authorization endpoint. The request includes the Client ID, requested scopes, a response_type=code, a redirect_uri (where the Auth Server should send the user back), and often a state parameter (for CSRF protection).
2. User Authentication & Consent: The Authorization Server authenticates the Resource Owner (e.g., asks for login). It then presents the requested scopes and asks the user for consent to grant the Client access.
3. Authorization Code Grant (B): If the user grants consent, the Authorization Server redirects the user's browser back to the Client's specified redirect_uri. The redirect URL includes a temporary, one-time use Authorization Code and the original state parameter.
4. Token Request (C - Back-Channel): The Client (using its backend) makes a direct, secure request to the Authorization Server's token endpoint. This request includes the received Authorization Code, its own Client ID, Client Secret (to authenticate the client itself), the redirect_uri (for verification), and grant_type=authorization_code.
5. Token Issuance (D): The Authorization Server verifies the code, Client ID/Secret, and redirect URI. If valid, it issues an Access Token (and optionally a Refresh Token) back to the Client. The Authorization Code is now invalidated.
6. Resource Request (E): The Client uses the obtained Access Token to make requests to the Resource Server (e.g., API calls), typically by including it in the Authorization: Bearer HTTP header.
7. Resource Response (F): The Resource Server validates the Access Token (checking signature, expiration, scopes). If valid and the token grants sufficient permission for the requested resource, the Resource Server returns the protected data to the Client.