- Stands for “Open Authorization”.
- Is an authorization protocol and NOT an authentication protocol.
- It replaced OAuth 1.0 in 2012 and is now the de facto industry standard for online authorization.
- Designed to allow a website or application to access resources hosted by other web apps on behalf of a user.
- Can also restrict which actions the client app can perform on resources on behalf of the user so the application’s access to the user’s account is limited to the scope of the authorization granted (e.g. read or write access).
- Uses Access Tokens. An Access Token is a piece of data that represents the authorization to access resources on behalf of the end-user. Although OAuth 2.0 doesn’t define a specific format for Access Tokens, JSON Web Token (JWT) format is often used.
For more information about JWT, you can read my post:
- Resource Owner is the user who authorizes an application to access their account.
- Client is the application that wants to access the user’s account. To access resources, the client must hold the appropriate access token (it must be authorized by the user and the authorization must be validated by the API).
- Authorization Server receives requests for access tokens from the client, verifies the identity of the user, then issues access tokens to the application.
The authorization server exposes two endpoints:
- Authorization endpoint handles the interactive authentication and consent of the user.
- Token endpoint is involved in a machine to machine interaction.
- Resource Server hosts the protected user accounts and receives access requests from the client. It accepts and validates an access token from the client and returns the appropriate resources to it.
- Scope specifies the level of access that the application is requesting from the client.
- Consent screen tells your users who is requesting access to their data and what kind of data you’re asking to access.
You should register your application through a registration form in the service’s website with your app’s name, website and a Redirect URI or a Callback URL (which you will be providing via your application).
Once registered, the service will issue client credentials in the form of a client identifier and a client secret. You will be using these two together in your application for authorization requests.
Client ID is a publicly exposed string that is used by the service API to identify the application.
Client Secret is used to authenticate the identity of the application to the service API and must be kept private between the application and the API.
The service will redirect the user (to the Redirect URI or Callback URL you have registered) after the authorization of your application so your application must be able to handle authorization codes or access tokens accordingly.
OAuth 2 defines three primary grant types:
1. Authorization Code: used with server-side Applications
2. Client Credentials: used with Applications that have API access
3. Device Code: used for devices that lack browsers or have input limitations
Protocol Flow for Grant Type: Authorization Code
Step 1 — Authorization Code Link
- the service API authorization endpoint
- client_id=the application’s client ID that is created by the service at the end of your application’s registration process
- redirect_uri=where the service will redirect the user-agent after an authorization code is granted.
- response_type=specifies that your application is requesting an authorization code grant
- scope=specifies the level of access that the application is requesting
Step 2 — User Authorizes Application
When the user clicks the authorization link, they will be welcomed with a screen to log in to the service to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize the application access to their account (with the requested permissions list).
Step 3 — Application Receives Authorization Code
If the user accepts to authorize the app, the service will redirect the user-agent to the application redirect URI with an authorization code. The redirect would look something like this.
Step 4 — Application Requests Access Token
The application requests an access token from the API by passing the authorization code along with authentication details, including the client secret, to the API token endpoint.
- the service API token endpoint
- client_id=the application’s client ID (as in authorization endpoint)
- redirect_uri=where the service will redirect the user-agent after an authorization code is granted. (as in authorization endpoint)
- client_secret=the application’s client secret that is created by the service at the end of your application’s registration process. Since this is private between your application and the API, you will mostly be keeping this value in your backend project’s properties file.
- grant_type=authorization_code is the value for this grant type
- code=the code that is sent as a parameter via your redirect URI in the previous step.
Step 5 — Application Receives Access Token
If the authorization is valid, the API will send a response containing the access token (and optionally, a refresh token) to the application.
Unlike access tokens, refresh tokens normally have long expiry times and may be exchanged for new access tokens when the latter expires. Because refresh tokens have these properties, they have to be stored securely by clients.
Step 6 — Access Token Usage
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" "https://service.api.com/v2/$OBJECT"
Once the application has an access token, it may use the token (in the Authorization header) to access the user’s account via the API, limited to the scope of access, until the token expires or is revoked.
Step 7 — Refresh Token Flow
- grant_type=authorization_code is the value for this grant type (as in token endpoint)
- client_id=the application’s client ID (as in both authorization and token endpoint)
You can store encrypted tokens securely in
Refresh token rotation guarantees that every time an application exchanges a refresh token to get a new access token, a new refresh token is also returned. If your Auth provider implements refresh token rotation, you can store them in local storage. The Auth provider should return a new refresh token every time that the client refreshes a JWT. It should also have a way of invalidating descendant refresh tokens if one refresh token is attempted to be used a second time.
- Popularity (Majority of big sites such as Google Docs, Dropbox, Spotify, etc.) support it with detailed documentation)
- Performed via HTTP / HTTPS with the token indicated in the headers, makes it easy to implement for mobile and desktop applications, on various sites, and even in browser plug-ins.
- No common format, as a result, each service requires its own implementation.
- The need for additional requests to get minimal user information.
- If your favorite sites are connected to the central hub and the central account is hacked, then it will lead to serious effects across several sites instead of just one.