OAuth2 is an authorization framework that enables applications to access user accounts on an HTTP service. This document describes OAuth 2 roles, grant types, use cases, and flows, geared towards application developers. OAuth2 provides access to resources hosted by other web apps on behalf of a user, without sharing the user's credentials. The specification also covers delegated access to client types such as browser-based, server-side web, native/mobile apps, and connected devices.
OAuth2 has different actors defined in the authentication and authorization process. These actors work together to ensure that the user's information is kept secure and that the application only accesses the information that the user has explicitly granted permission for.
The user: "resource owner"
The resource owner is the person or system that owns protected resources, such accounts, a files, or data, and has the ability to grant access to them. In the context of OAuth2 and OpenID Connect, the resource owner is typically a user who has an account in a service or application.
When an application wants to access a resource owner's account, it must first request authorization from the resource owner. The resource owner has the ability to limit the application's access to their account to a specific scope, such as read or write access. This means that the application can only access the user's account within the limits of the authorization granted.
For example, if a user wants to use an application that requires access to their email account, the user must first grant the application permission to access their account. The user can choose to grant access only to specific emails or folders, or limit the application's access to read-only mode. The resource owner is in complete control of who can access their account and what level of access they are granted.
With Ory OAuth2 and OpenID Connect, developers have the flexibility to use their own user management systems to store and manage resource owners, while still taking advantage of the robust authorization and authentication mechanisms provided by the OAuth2 and OpenID Connect protocols.
By default, Ory Identities is used to store and manage resource owners in the Ory Network.
The application: "OAuth2 client"
The OAuth2 client is the application that requires access to protected resources, such as a user's account details or data. Before the client can access these resources, it must first get an access token, which serves as proof of authorization to access the requested resources. The client must first be authorized by the resource owner and must hold a valid access token in order to access protected resources. The API server that hosts the protected resources will validate the access token to ensure that the client is authorized to access the requested resources.
The API: "resource server"
The resource server is a server that hosts and protects the user's resources, such as their account information or data. It is typically an API server that exposes a set of endpoints that allow clients to access the protected resources. The resource server receives access requests from the OAuth2 client and verifies the access token presented with the request to ensure that the request is authorized. If the access token is valid and authorized, the resource server returns the appropriate resources to the client. If the access token is invalid or unauthorized, the resource server returns an error message to the client.
The authorization server: Ory OAuth2 and OpenID Connect
The authorization server is a critical component in OAuth2 flows. It receives requests from the client for access tokens and issues them upon successful authentication and consent by the resource owner. The authorization server exposes two endpoints: the Authorization endpoint and the Token endpoint. The Authorization endpoint is responsible for handling the interactive authentication and consent of the user, while the Token endpoint is involved in a machine-to-machine interaction.
The Authorization endpoint is where the resource owner approves or denies the request from the client. This endpoint presents an interface to the resource owner that allows them to view the scope of the requested access and make an informed decision about whether to grant or deny access to their resources. In smaller implementations, the authorization server may be combined with the API server, but larger scale deployments will often build this as a separate component.
OAuth2 scopes represent user consent
OAuth2 scope is a parameter used to specify the level of access that OAuth2 clients have to protected resources. It allows resource owners to define specific permissions or actions that a client is authorized to perform in their name.
Scopes are an important concept in OAuth2 as they are used to specify the exact level of access to resources that can be granted. For example, a scope may include read access to a user's email, write access to a user's calendar, or access to a specific set of files. The acceptable scope values, and which resources they relate to, are dependent on the resource server.
Ory OAuth2 and OpenID Connect has pre-defined OAuth2 scope values:
offline_access: Include this scope if you want to receive a refresh token
openid: Include this scope if you want to perform OpenID Connect requests.
Scopes vs permissions
What's the difference between scopes and permissions? Scopes define what the client is authorized to access in the name of the user. Permissions (RBAC, ACL) define what the user themselves are allowed to do. By using scopes, users can control the level of access that clients have to protected resources. Permissions ensure a user has access to their resources only, not the resources of other users.
OAuth2 access token audience
The audience of an access token are the resource servers that this token is intended for. The audience usually refers to one or more URLs such as
- One or more URLs:
- A subset of resources:
When performing an OAuth2 flows where the user is involved, for example Implicit Grant or Authorization Code Grant, the granted
audience must be set when accepting the consent using the
grant_access_token_audience key. In most cases, it's ok to grant the
audience without user interaction.
Creating OAuth2 clients
Creating an OAuth2 client is a necessary step to enable your application to use OAuth2 flows. Before using OAuth with your application, you must register your application with the service you plan to integrate with. This is done through a registration form in the developer or API portion of the service's website, where you provide the following information about your application:
- Application name
- Application website
- Redirect URI or callback URL.
The application name and website are basic pieces of information that identify your application. The redirect URI or callback URL is a crucial part of the registration process as it defines where the service redirects the user after the user authorizes (or denies) your application. The redirect URI is also where your application handles authorization codes or access tokens, making it an important component of the OAuth2 flow.
It is important to ensure that the redirect URI or callback URL is correctly specified during the registration process, as it's a critical part of OAuth2 flows. Without a correctly specified redirect URI, OAuth2 flows can't be completed successfully, resulting in an error for the user.
Client ID and secret
token_endpoint_auth_method parameter is an optional parameter used to specify the client authentication method when
requesting an access token. This parameter is included in the request to the token endpoint and can be set to a variety of values,
none. The value of this parameter can affect how the client
authenticates itself to the authorization server.
For example, if the value of the
token_endpoint_auth_method parameter is set to
client_secret_basic, the client authenticates
itself to the authorization server by including the client ID and client secret in the
Authorization header of the request:
Authorization: Basic base64(urlencoded(id):urlencoded(secret))
If the value of the
token_endpoint_auth_method parameter is set to
client_secret_post, the client authenticates itself to the
authorization server by including the client ID and client Secret in the form body of the request:
none method is typically used for public clients, such as Single-Page Applications (SPAs) and mobile apps, which are not
capable of keeping a client secret confidential. When the
token_endpoint_auth_method parameter is set to
none, the client
doesn't include any credentials when requesting an access token. This means that the client relies solely on the redirect URI to
securely receive the access token, rather than using a shared secret to authenticate itself to the authorization server.
Getting a client token
OAuth2 defines several grant types, each of which is intended for a specific type of client application.
Client credentials flow
The client credentials flow is designed for non-interactive applications, such as automated processes or microservices, where the client is authenticated using its client ID and client secret. In this flow, the application sends a POST request to the authorization server, including its credentials and a request for an access token. If the credentials are verified, the authorization server returns an access token to the application, which can then use it to access its own account.
For more information, see the Client Credentials Flow.
Authorization Code Flow
The Authorization Code Flow, is the most commonly used OAuth2 flow. It's optimized for server-side applications where client secret confidentiality can be maintained. In this flow, the user is first presented with an authorization code link that includes the application's client ID and other parameters, such as the redirect URI and the requested scope of access. After the user approves the application, the service redirects the user-agent to the redirect URI specified by the application, including an authorization code. The application then exchanges this code, along with its client secret, for an access token using the token endpoint.
It's worth noting that in this flow, the client secret cannot be stored securely, since it needs to be included in the request to the token endpoint. For this reason, single-page applications and mobile/native apps are often not appropriate for this flow, and should instead use the authorization code with PKCE grant. In addition, the scope parameter is used to specify the level of access that the application is requesting, and acceptable scope values are dependent on the resource server. Overall, the authorization code flow is a redirection-based flow that relies on the user-agent (the user's web browser) and API authorization codes to securely handle authentication and consent.
For more information, see the OAuth2 Authorization Code Flow.
Use case examples
Server-side web apps
Server-side web applications, such as those built with Node.js or PHP, are typically best suited to using the OAuth2 Authorization Code Flow. This is because server-side applications can keep the client secret confidential, which is necessary for using the Authorization Code Flow.
In addition, it's recommended that server-side web applications use the Authorization Code Flow with the Proof Key for Code Exchange (PKCE) extension to provide an added layer of security. The PKCE extension helps to mitigate the risk of attacks by requiring the client to generate a code verifier for every authorization request, which is then transformed into a code challenge and sent to the authorization endpoint along with the request.
The OAuth2 Authorization Code Flow is the recommended flow to use with mobile applications. Because mobile apps are considered public clients, it's highly recommended to use the Authorization Code Flow with the PKCE extension.
Single-page applications (SPAs) are web applications that run inside a web browser and dynamically update the page as the user interacts with the application. Because the client-side code of an SPA is fully exposed to the user, it's not safe to store a client secret in the application. As a result, SPAs should also use the OAuth2 Authorization Code Flow flow with PKCE to ensure the client secret is not exposed.
For example, an SPA that uses OAuth2 to access Google APIs would use the Authorization Code Flow with PKCE. When the user clicks the "Sign in with Google" button, the SPA redirects the user to Google's authorization endpoint, where they are prompted to grant permission for the application to access their Google account. If the user grants permission, Google will return an authorization code to the SPA. The application can exchange the code for an access token using the token endpoint. The SPA can then use the access token to access the user's data through Google APIs. By using PKCE, the SPA can ensure that the authorization code cannot be intercepted and used by an attacker.
The Device Code Flow is designed for devices that have limited inputs or do not have a web browser, and need to obtain an access token to access a user's account. This grant type provides an easier way for users to authorize applications on such devices to access their accounts. It is particularly useful in scenarios where users want to sign in to an application on a device that lacks a typical keyboard input, such as a smart TV or video game console.
With the Device Code grant type, the user initiates the flow on a separate device, such as a phone or computer, and is presented with a Device Code. The user then enters this code on the device that needs to obtain the access token. This device will periodically poll the authorization server until the user grants or denies the authorization request. Once the user grants access, the device receives an access token that can be used to access the user's account.
Sending an access token to a resource server usually involves including the token in the HTTP
Authorization header of the
const fetch = require("node-fetch")
const accessToken = "your_access_token_here"
Authorization: "Bearer " + accessToken,
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error(error))
In this example, the access token is included in the
Authorization header of the GET request sent to the resource server API
Bearer keyword indicates that the token is a bearer token, which is a type of access token that can be used by any
client to access the protected resources. The resource server then verifies the token and grant or deny access based on the
token's validity and the scope of access that was granted.
The resource server needs to ensure that the access token is valid and has not been tampered with or expired before allowing access to protected resources. To achieve this, the resource server uses the OAuth2 token introspection endpoint, which is an API endpoint exposed by Ory.
Resource Owner Password Credentials flow
Ory doesn't support the resource owner Password Credentials Grant Type as we prepare for OAuth 2.1 which removed this grant type.
As the industry has evolved, so has the best practice for implementing OAuth2 in mobile and native apps. Previously, the Implicit grant was recommended, but it has since been found to be less secure. The current recommendation is to use the Authorization Code with PKCE for native apps, which provides greater security for both the user and the application.