The possession of great power necessarily implies great responsibility.
—William Lamb, British Member of Parliament, Home Secretary, and Prime Minister. From a speech in the House of Commons, 1817
Modern applications are often designed around APIs. APIs enable applications to reuse logic and take advantage of innovative services. APIs provide access to valuable data or services, so they typically need to restrict API access to authorized parties. Applications therefore need authorization to call APIs. If an application wants to call an API on a user’s behalf to access resources owned by the user, it needs the user’s consent. In the past, a user often had to share their credentials with the application to enable such an API call on their behalf. This gave the application an unnecessary amount of access, not to mention the responsibility of safeguarding the credential. In this chapter, we will cover how the OAuth 2 Authorization Framework provides a better solution for authorizing applications to call APIs.
In this chapter, we will provide an overview of the OAuth 2 Authorization Framework aligned with the draft OAuth 2.1 version (draft 6) of the specification.i OAuth 2.1 is a consolidation of the earlier OAuth 2.0 Authorization Framework,ii several subsequent specifications, and security best practice documents. We will also point out key elements of the framework which changed or were removed between OAuth 2.0 and OAuth 2.1. At the time of writing, OAuth 2.1 is still in draft status, so there may be further revisions in the future. Application owners and developers should check for ongoing changes and best practice guidance.
For the remainder of this chapter, we will use the term OAuth 2 when describing benefits or impacts of the OAuth Authorization Framework in general. We will use the term OAuth 2.1 when specifically referring to the OAuth 2.1 Authorization Framework specification and OAuth 2.0 when specifically referring to the OAuth 2.0 Authorization Framework specification.
API Authorization
A flow diagram illustrates A P I authorization. An application communicates with A P I 1 to access famous literary quotes on its own behalf and with A P I 2 for the user's documents on the user's behalf. A mobile application calls A P I 2 on the user's behalf for accessing user documents.
API Authorization: User-Based vs. Client-Based Flow
In this scenario, the application, WriteAPaper.com, is a specialized editor that helps users write and edit research papers. It calls two APIs, both of which are owned by different organizations. The first is famousquotes.com which provides validated quotes for use in papers. The second API is at documents.com and provides a document storage service. There is a second, mobile application that calls the documents.com API to provide access to documents from a user’s mobile device.
When the WriteAPaper application calls the API at famousquotes.com, it does so on its own behalf. The quotes content is not owned by the user, so the user’s consent isn’t needed for this access. The application only needs to be a registered client authorized to call the quotes API. When the application calls the API at documents.com, however, to obtain a user’s documents, the request must be made on behalf of the user. In this case, the content accessed belongs to the user, and the application must obtain the user’s consent to retrieve the user’s documents. The client application has no right by itself to access the user’s data at another site.
The mobile application provides read-only access to a user’s documents and doesn’t offer access to the quotes service. It requires authorization from a user to call the documents API and retrieve the user’s documents. We’ve included the mobile application in the example because we’ll show in the following sections how OAuth 2 could be used to enforce different privileges for the two applications.
OAuth 2
The OAuth 2 Authorization Framework, originally published as OAuth 2.0 in 2012 and revised starting in 2020, and continuing through 2022 to create OAuth 2.1, was designed to enable an application to obtain authorization to call third-party APIs. With OAuth 2, an application can obtain a user’s consent to call an API on their behalf, without needing the user’s credentials for the API site. An application can also obtain authorization to call an API on its own behalf if it owns the content to be accessed.
The primary use case involves a user, called a resource owner, who wishes to allow an application to access a protected resource, owned by the resource owner, at a logically separate site, known as the resource server. Using our example from Figure 5-1, the resource owner (the user) has stored documents at a resource server (documents.com). The resource owner is using the WriteAPaper application to write a paper based on content they’ve uploaded to documents.com. The resource owner wants to grant the WriteAPaper application access to their content at documents.com so it can retrieve the content for use in their research paper.
A 3 block diagram for access requests includes a user, an application, and documents A P I in the backend. The diagram shows the interactions of the components. The user provides credentials to the application, and finally calls for documents A P I to retrieve data.
Access Requests Prior to OAuth 2
OAuth 2 provides a better solution. OAuth 2 enables a user to explicitly authorize an application to call an API on the user’s behalf, without giving their credentials for the API site to the application and in a way that limits what the application can do. With OAuth 2, when an application needs to call an API on behalf of a user, it sends an authorization request to an authorization server for the API. An authorization server handles access requests for an API and returns a security token that can be used by the application to access the API. In the authorization request, the application gives an indication of what it wants to request from the API. The authorization server evaluates the request and, if authorized, returns a token to the application.
A 5 step block diagram for access requests. In step 1, the user accesses the application and requests access via the authentication server in step 2. In step 3, the user gives consent for access. In step 4 the authentication server provides an access token for the application, and it calls for documents A P I in step 5.
Access Requests with OAuth 2
To recap, the OAuth 2 protocol provides an authorization solution, not an authentication solution. It enables an application to call an API on its own behalf or a user’s behalf, with the call constrained to the scope of an authorized request. The authentication step in OAuth 2 validates the user is entitled to give consent to authorize an access request for a particular resource. The OAuth 2 access token is only intended for API access and not to convey information about the authentication event or the user. The use of OAuth 2 is therefore appropriate for authorizing API calls but not as an authentication solution (at least in the absence of any proprietary additions to the base protocol, which some providers have implemented). OIDC, described in the next chapter, can be used to authenticate a user to an application, but this chapter focuses on describing how OAuth 2 works for the purpose of API authorization.
Terminology
To describe OAuth 2 in more detail, we need to describe a few terms.
Roles
Resource Server – A service (with an API) storing protected resources to be accessed by an application.
Resource Owner – A user or other entity that owns protected resources at the resource server.
Client – An application which needs to access resources at the resource server, on the resource owner’s behalf or on its own behalf. We’ll generally use the term application instead of client, for consistency across chapters.
Authorization Server – A service trusted by the resource server to authorize applications to call the resource server. It authenticates the application or resource owner and requests consent from the resource owner if the application will make requests on the resource owner’s behalf. With OAuth 2, the resource server (API) is a relying party to the authorization server. The authorization server and resource server may be operated by the same entity.
Confidential and Public Clients
Confidential Client – An application that can securely store confidential secrets with which to authenticate itself to an authorization server or use another secure authentication mechanism for that purpose. Confidential clients typically execute primarily on a protected server.
Public Client – An application that can neither securely store a secret or credentials to authenticate itself to an authorization server nor use another secure authentication mechanism for that purpose. Public clients typically execute primarily on the user’s client device or in the client browser.
Client Profiles
Web Application – A confidential client with code executing on a protected, back-end server. The server can securely store any secrets needed for the client to authenticate itself as well as any tokens it receives from the authorization server. Such credentials and tokens are not exposed to the resource owner.
Browser-Based Application – Assumed to be a public client with code executing in the user’s browser. Example: A JavaScript-based, single-page application running in the browser. Such an application is assumed to be incapable, with current technology (at the time of writing), of adequately securing credentials with which to authenticate itself to an authorization server.
Native Application – Assumed to be a public client that is installed and executed on the user’s device, such as a mobile application or desktop application.
In practice, these definitions may overlap because a web application may serve up HTML pages that contain some JavaScript, and single-page applications may have a small back end. For further discussion on this, see the description in Chapter 6 of the OIDC Hybrid Flow.
Tokens and Authorization Code
Authorization Code – An intermediary, opaque code returned to an application and used to obtain an access token and optionally a refresh token. Each authorization code is used once.
Access Token – A token used by an application to access an API. It represents the application’s authorization to call an API and has an expiration.
Refresh Token – An optional token that can be used by an application to request a new access token when a prior access token has expired.
How It Works
The OAuth 2 Authorization Framework defines different methods by which an application interacts with an authorization server to obtain authorization to call an API. Each method uses a credential to represent the authorization. These credentials are known as authorization grants and are used by an application to obtain an access token with which to call an API. The type of authorization grant to use depends on the use case.
Authorization code
Client credentials
Refresh token
Implicit (removed)
Resource owner password credentials (removed)
Client device
The following sections will describe how each of these authorization grant types work, as well as why the obsolete authorization grant types were removed.
Authorization Code Grant
A schematic representation of authorization code grant. It has 5 components of user, browser, application, authorization server, and resource server. The diagram has 8 steps of interaction between the blocks for login credentials, authorization code, access token, refresh token, code verifier, code challenge, and code challenge method.
Authorization Code Grant Type + PKCE
- 1.
The user (resource owner) accesses the application.
- 2.
The application redirects the browser to the authorization server’s authorize endpoint2 with an authorization request.
- 3.
The authorization server prompts the user for authentication and consent.3
- 4.
The user authenticates and provides consent for the request.
- 5.
The authorization server redirects the user’s browser back to the application’s callback URL4 with an authorization code.
- 6.
The application calls the authorization server’s token endpoint,5 passing the authorization code.
- 7.
The authorization server responds with an access token (and optionally a refresh token).
- 8.
The application calls the resource server (API), using the access token.
The authorization code grant type was originally optimized for confidential clients. The first (authorization) request redirects the user to the authorization server so it can interact with the user. The second request could be made by the application’s back end directly to the authorization server’s token endpoint. This enables an application back end, which is assumed to be capable of securely managing an authentication secret, to authenticate itself to the authorization server when exchanging the authorization code for the access token. It also means that the response with the access token can be delivered to the application back end, which will make the subsequent API calls. An added side benefit is that the tokens are returned via secure back-channel response. However, while originally optimized for confidential clients, the addition of PKCE enables other client types to use this grant type as well.
Authorization Code Grant Type + PKCE
The authorization code grant type diagram shows the use of Proof Key for Code Exchange (PKCE).iii PKCE is a mechanism that can be used with authorization and token requests to prevent a malicious process, especially on mobile devices and with public clients, from intercepting an authorization code and using it to get an access token. PKCE does not authenticate clients. Rather, it ensures that the application that requested an authorization code is the same application that uses the authorization code to obtain an access token. PKCE was defined after OAuth 2.0, but has been incorporated into the core OAuth 2.1 specification for use with the authorization code grant type.
To use PKCE, the application creates a cryptographically random string, called a code verifier, that is long enough to provide sufficient protection against guessing. The application then computes a derived value, called a code challenge, from the code verifier. This derived value is typically a hash of the code verifier. It should not be possible to compute the code verifier from the derived value in a time period that would enable compromising the transaction. When the application sends an authorization request in step 2 in the diagram, it includes the code challenge, along with the method used to derive it.
When the application sends the authorization code to the authorization server’s token endpoint to get the access token in step 6, it includes the code verifier. The authorization server transforms the code verifier value using the transformation method received in the authorization request and checks that the result matches the code challenge sent with the authorization request. This enables an authorization server to detect if a malicious application is trying to use a stolen authorization code. Only the legitimate application will know the code verifier to pass in Figure 5-4’s step 6 that will match the code challenge passed in step 2.
The PKCE specification lists two transform methods that can be used to derive the code challenge from the code verifier, namely, “plain” and “S256.” With the “plain” method, the code challenge and verifier are identical, so there is no protection against the code challenge being compromised. Applications using the authorization code grant with PKCE should use the S256 transform method which uses a base64 URL encoded SHA256 hash of the code verifier to protect it.
The Authorization Request
Authorization Request Parameters
Parameter | Meaning |
|---|---|
response_type | Indicates the OAuth 2 grant type. “code” is used for the authorization code grant type. |
client_id | Identifier for the application, assigned when it registered with the authorization server. |
state | A nonguessable string, unique for each call, opaque to the authorization server, and used by the client to track state between a corresponding request and response to mitigate the risk of CSRF attacks. It should contain a value that associates the request with the user’s session. This could be done by including a hash of the session cookie or other session identifier concatenated with an additional unique-per-request component. When a response is received, the client should ensure the state parameter in the response matches the state parameter for a request it sent from the same browser. This parameter should not include any sensitive information in plain text. |
scope | Indicates the scope of access privileges for which authorization is requested. For example: “get:documents”. This parameter should not include any sensitive information in plain text. |
redirect_uri | The authorization server sends its response with the authorization code to this callback URL at the application. The specified URI must exactly match the callback URI previously registered at the authorization server for the client application. For example: https%3A%2F%2Fclient%2Eapplication%2Ecom%2Fcallback. (An exception to the exact match requirement is noted for the port number in local host redirect URLs in native applications.) |
resource | Identifier for a specific API registered at the authorization server for which the access token is requested. Some implementations may use other names, such as “audience.” Primarily used in deployments with custom APIs. This parameter isn’t needed unless there are multiple possible APIs. |
code_challenge | PKCE code challenge derived from the PKCE code verifier using the code challenge method specified in the code_challenge_method parameter, as described in Section 4.2 of the PKCE specification.iv |
code_challenge_method | “S256” or “plain.” Applications capable of using S256 must use it. |
The scope parameter is used by an application to request a scope of access privileges. Using our WriteAPaper application example from the beginning of the chapter, the primary, single-page application would request a scope of “get:documents update:documents,” whereas if the mobile client only needed read access to documents, it would only request “get:documents.” There are additional parameters available which applications can use to express richer, more detailed authorization requests. These will be discussed in Chapter 8.
The redirect_uri parameter must exactly match a redirect URI specified at the time the client application was registered with the authorization server. While OAuth 2.0 allowed the URI registered with the authorization server to contain wildcards, OAuth 2.1 now disallows the use of wildcards in the redirect URI registered for a client application. This change reduces the possibility of open redirect attacks.
The resource parameter was not in the original OAuth 2.0 specification. Since that time, authorization servers have been written to handle requests for multiple APIs and, in such cases, may support an additional parameter to indicate a specific API for an authorization request. This parameter is defined in the Resource Indicators for OAuth 2.0 extension.v This parameter may be called the “resource” or “audience” depending on the authorization server implementation.
Response
Authorization Response Parameters
Parameter | Meaning |
|---|---|
code | The authorization code to be used by the application to request an access token. |
state | The state value, unmodified, sent in the authorization request. The application must validate that the state value in the response matches the state value sent with the initial request. |
Calling the Token Endpoint
Token Request Parameters
Parameter | Meaning |
|---|---|
grant_type | Must be “authorization_code” for the authorization code grant. |
code | The authorization code received in response to the authorization call. |
client_id | Identifier for the application, assigned when it registered with the authorization server. |
code_verifier | The PKCE code verifier value from which the code challenge was derived. It should be an unguessable, cryptographically random string between 43 and 128 characters in length, inclusive, using the characters A–Z, a–z, 0–9, “-”, “.”, “_”, and “~” and formed as described in Section 4.1 of the PKCE specification.vi |
redirect_uri | The callback URI for the authorization server’s response. Should match the redirect_uri value passed in the authorization request to the authorize endpoint. |
Token Endpoint Response Parameters
Parameter | Meaning |
|---|---|
access_token | The access token to use in calling the API. Different authorization servers may use different formats for access tokens. |
token_type | Type of token issued. “Bearer,” for example. |
expires_in | How long the token will be valid. |
refresh_token | A refresh token is optional. It is up to an authorization server’s discretion whether to return a refresh token or not. See the “Refresh Tokens” section later in this chapter for further information. |
An authorization server may include an additional parameter “scope” to indicate the actual scope of access granted with the issued access token. This is necessary when an authorization server issues an access token for a more restrictive scope than requested by the client.
There are different types of access tokens in use. Some authorization servers issue an opaque access token in the form of an encoded string. A resource server receiving such an access token can call a token introspection endpoint at the issuing authorization server to obtain information about the token, such as the client that requested the token, the intended audience (resource server) for the token, the token expiration, whether the token has been revoked, and the scopes included in the token. The OAuth 2.0 Token Introspection specificationvii defines the token introspection endpoint and how resource servers can use it to obtain information about opaque tokens issued by authorization servers.
Another common format for access tokens is a JSON Web Token (JWT). This is a structured format that is cryptographically signed and contains various claims about the token such as the client that requested the token, the intended audience (resource server), when the token expires, and the scopes authorized for the token. With self-contained tokens, a resource server can obtain the claims directly from the token without having to call a token endpoint at an authorization server. The JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokensviii defines this type of token along with a set of mandatory and optional claims. The documentation for your authorization server should indicate the type of access token it issues and the steps a resource server should take to validate the token and obtain the claims represented by the token.
Client Credentials Grant
A schematic representation of client credentials grant. It has 3 components of application, authorization server, and resource server. The diagram has 6 steps of interaction between the blocks for login credentials, and access token.
Client Credentials Grant Type
- 1.
The application sends an authorization request including the application’s credentials to the authorization server.
- 2.
The authorization server validates the credentials and responds with an access token.
- 3.
The application calls the resource server (API) using the access token.
- 4.
The steps repeat if the access token has expired by the next time the application calls the API.
No end-user interaction with the authorization server is required for this flow. The application credentials serve as the authorization for the application and are used to request an access token from the token endpoint. Our sample uses a client ID and client secret obtained when the application registered with the authorization server.
The Authorization Request
A successful client credentials grant request will result in a response from the token endpoint with an access token, similar to the example in the previous section for the authorization code grant.
Implicit Grant (Removed in OAuth 2.1)
The implicit grant type was removed in OAuth 2.1. It is included here to explain its original purpose, why it is no longer needed, and what should be used in its place.
A schematic representation of implicit grant type. It has 5 components of user, browser, application, authorization server, and resource server. The diagram has 6 steps of interaction between the blocks for login credentials, and access token.
OAuth 2.0 Implicit Grant Type (Removed in OAuth 2.1)
- 1.
The user (resource owner) accesses the application.
- 2.
The application redirects the browser to the authorization server’s authorize endpoint with an authorization request.
- 3.
The authorization server prompts the user to authenticate and provide consent.7
- 4.
The user authenticates and provides consent for the authorization request.
- 5.
The authorization server redirects back to the application’s callback URL with an access token.
- 6.
The application uses the access token to call the resource server (API).
Since the OAuth 2.0 specification was originally published, CORS has become supported by most browsers. Consequently, the implicit grant type isn’t needed anymore for its original purpose. Furthermore, returning an access token in a URL hash fragment exposes the access token to potential leakage via browser history or referer headers. The OAuth 2.0 implicit grant type has therefore been removed from OAuth 2.1.x The authorization code grant type with PKCE should be used instead.
New applications should avoid the use of the implicit grant type. For existing applications, it is possible that existing authorization servers will continue to support the use of the implicit grant for some time. However, given the security concerns associated with this grant type, existing applications should migrate to the authorization code grant type with PKCE to reduce the risk from leaked tokens, avoid a rushed upgrade if an authorization server decides to end support for the implicit grant, and align with OAuth 2.1.
Resource Owner Password Credentials Grant (Removed from OAuth 2.1)
The resource owner password credentials grant type was removed from OAuth 2.1. It is included here to explain its initial purpose and why it should not be used.
With the OAuth 2.0 resource owner password credentials grant type, the application collected the user’s credentials directly instead of redirecting the user to the authorization server. The application passed the collected credentials to the authorization server for validation as part of its request to get an access token. This grant type was intended to support situations where an application was trusted to handle end-user credentials and no other grant type was possible.
A schematic representation of resource owner password grant type. It has 5 components, user, browser, application, authorization server, and resource server. User interacts with application for login credentials, application interacts with authorization server via login credentials, in turn provides access and refresh token. Application calls resource server via access token.
Resource Owner Password Credentials Grant Type (Removed from OAuth 2.1)
- 1.
The user (resource owner) accesses the application.
- 2.
The application prompts the user for their credentials.8
- 3.
The user provides their credentials to the application.
- 4.
The application sends a token request to the authorization server’s token endpoint, with the user’s credentials.
- 5.
The authorization server responds with an access token (and optionally a refresh token).
- 6.
The application calls the resource server (API), using the access token.
The use of this grant type was not actively encouraged for several reasons. First, it exposed the user’s credentials to the application. A vulnerability in the application could compromise the user’s credentials. There was also no specification for how to extend this grant to provide multi-factor authentication, so applications might have added multi-factor authentication capabilities in custom ways that might not have received adequate security review. In addition, this grant type did not involve a user consent step, so an application could request any access it wished using the user’s credentials. The user had no way to prevent abuse of their credentials.
This grant type has been used for mobile apps, legacy embedded login pages, and user migration scenarios. Some mobile applications used this grant type when calling first-party APIs. This was often done because login flows that redirected via browsers on mobile devices were originally perceived as cumbersome. This has since improved, and OAuth 2.1 has incorporated the guidance of RFC 8252, OAuth 2.0 for Native Apps,xi to use the authorization code grant, combined with PKCE, for native applications using the system browser.
This grant type was also used when login fields were embedded within an application page. This was often done to conform to corporate user interface standards or simply a desire to have an embedded login screen rather than the disruption of a browser redirect. For the reasons stated earlier, this grant type has been removed from OAuth 2.1. Applications should redirect users to the authorization server using the authorization code grant type with PKCE, rather than collect user credentials themselves.
Another scenario for this grant type was user migration use cases. When users needed to be migrated from one identity repository to another with incompatible password hashes, the new system could prompt a user for their credentials, use the resource owner password grant to validate them against the old system, and, if valid, retrieve the user profile from the old system and store it and the credentials in the new system. This avoided the necessity for large-scale forced password resets when migrating identity information. However, if passwords in the old system were compromised, either directly or via password reuse, this scheme would add vulnerable accounts to the new system, unless password checks were implemented as part of the transfer.
To mitigate some of the risk associated with this grant type, the client was supposed to throw away the user credentials as soon as it had obtained the access token, to reduce the possibility of compromised credentials. This guidance, however, only addresses one aspect of the risk associated with this grant type. With other risks remaining, the resource owner password credentials grant type has been removed from OAuth 2.1.xii New applications should avoid the use of this grant type. For existing applications, it is possible that existing authorization servers will continue to support this grant type for some time. However, given the security and liability concerns associated with this grant type, existing applications should migrate to the authorization code grant type with PKCE to reduce the risk from credentials exposed to client applications, facilitate use of multi-factor authentication, and avoid a rushed upgrade if an authorization server decides to end support for this grant type. While legacy applications that cannot be upgraded will probably continue to use this grant type for some time, application owners should understand that applications that continue to use the resource owner password credentials grant type will have the responsibility and liability associated with reviewing the security of their approach. They also risk being forced to upgrade if their identity provider ends support for this grant type.
Device Authorization Grant
Since the publication of OAuth 2, there has been a proliferation of Internet-connected devices often called the Internet of Things (IoT). As with applications, the functionality of IoT devices can be greatly enhanced by calling APIs. A classic example is a digital picture frame. Rather than manually uploading photos to a digital picture frame, it would be nice if you could simply authorize the frame to retrieve photos you have already uploaded to a social media site. This requires you as the owner of the pictures to authenticate to the social media site and provide your consent for the frame to retrieve photos from your account.
The OAuth 2 authorization code grant requires user interaction on the client device for authentication and authorization, yet a digital picture frame and many IoT devices have very limited facilities for user interaction. While a digital frame might be able to implement a touch screen and some limited browser capability to support the redirects and input required, that would increase the complexity and cost of the device which may not be feasible for such devices from a technical or business perspective.
The OAuth 2.0 Device Authorization Grantxiii provides a mechanism for the user interaction to occur on another device. With this grant, the user triggers an action on the primary device (an IoT device) that requires an API call. This action could be anything from turning on a device like a TV or making a specific request such as retrieving pictures from a specific social media account. In response to the action, the primary device initiates an authorization request to the authorization server for the API. The authorization server responds with a URL and code that the primary device displays to the user, along with instructions.
The user follows the instructions and accesses the URL on a secondary device, such as a mobile phone. The user interacts with the authorization server on the secondary device to authenticate, input their code, and provide their authorization for the requested action. While the user is doing this, the primary device polls the authorization server. Once the user has completed the interaction on the secondary device, the primary device’s next polling request will result in a successful response with an access token and, optionally, a refresh token. The primary device can then use the access token to make an API call on the user’s behalf.
A schematic representation of device authorization grant. It has 5 components, user, browser on secondary device, primary client device, authorization server, and resource server. The diagram has 12 steps of interaction between the blocks via login credentials, authorization code, access token, refresh token, client ID, device code, end user code, and verification URL.
Device Authorization Grant
- 1.
The user (resource owner) accesses the primary device.
- 2.
The primary device sends an authorization request to the authorization server for the API. This request includes the device’s client ID.
- 3.
The authorization server responds with a device code, end-user code, and a user verification URI.
- 4.
The primary device displays or communicates to the user the URI and end-user code.
- 5.
The user accesses the verification URI on a secondary device such as a phone.
- 6.
The authorization server interacts with the user on the secondary device to authenticate them.
- 7.
The user supplies their login credentials to the authorization server.
- 8.
The authorization server prompts the user for their user code and for authorization of the API call.
- 9.
The user supplies their end-user code and approves the authorization request.
- 10.
The primary device continually polls the authorization server.
- 11.
When the user approves the request, the authorization server responds to the next polling request with an access token and optionally a refresh token.
- 12.
The primary device can then use the access token to call the API on the user’s behalf.
There are several requirements for this Device Authorization Grant to work. The primary device must be connected to the Internet, and the device must be capable of making outbound HTTPS requests to the authorization server for the desired API. The primary device must also be capable of displaying or communicating to the user the user verification URI, an end-user code, and instructions for how to proceed. This grant also requires the user to have a secondary device capable of supporting the user interaction to authenticate and authorize the API requests.
The following sections show the steps for the Device Authorization Grant in more detail.
The Authorization Request
Authorization Request Parameters
Parameter | Meaning |
|---|---|
client_id | Identifier for the primary device, assigned when it registered with the authorization server. |
scope | The scope of access privileges for which authorization is requested. For example: “get:photos”. |
resource | Identifier for a specific API registered at the authorization server and for which the access token is requested. Some implementations may use other names, such as “audience.” Primarily used in deployments with custom APIs. This parameter isn’t needed unless there are multiple possible APIs. |
The scope parameter is used by the primary device to request a scope of access privileges. Using our digital photo frame example, the digital frame would request a scope of “get:photos” as it needs to retrieve photos for display in the frame. There are additional parameters which can be used to express richer authorization requests and which will be discussed in Chapter 8.
An authorization server may support a parameter to indicate a specific API for an authorization request as defined in the Resource Indicators for OAuth 2.0 extension.xiv This parameter may be called the “resource” or “audience.”
Authorization Response
Authorization Response Parameters
Parameter | Meaning |
|---|---|
device_code | A code generated by the authorization server for the primary device, to be used by the device when it makes the subsequent token request. |
user_code | A code generated by the authorization server for a particular end user’s device authorization session, to be used when the user subsequently interacts with the authorization server on a secondary device to authorize the primary device’s request. |
verification_uri | A URI to be displayed or communicated to the user by the primary device, along with instructions for the user to access that URI from a secondary device to consent to the authorization request. |
expires_in | Validity period for the device_code and user_code. Specified in seconds. |
interval | Minimum time, specified in seconds, that the primary device should wait between polling requests. |
The primary device receives an authorization response with a user verification URI, a device code, and a user code. The primary device communicates the verification URI and user code to the user in any format suitable for the device and which facilitates the user’s interaction. For example, the primary device could display a text URL or a QR code. The primary device also provides instructions for the user to navigate to the verification URI on a secondary device, such as a smartphone, and enter the user code when prompted. The secondary device needs to have a user agent, such as a browser, that can support redirects to the authorization server. It also must allow the user to interact with the authorization server for authentication and consent.
When the user navigates to the verification URI, the authorization server will prompt the user to log in, enter the user code, and consent to the authorization request. The exact sequence and process for this interaction may vary by authorization server.
While the user is interacting with the authorization server on the secondary device, the primary device periodically polls the authorization server.
Polling the Authorization Server
Token Request Parameters
Parameter | Meaning |
|---|---|
grant_type | Indicates the type of grant requested. For this scenario, it must be set to “urn:ietf:params:oauth:grant-type:device_code”. |
device_code | A code generated by the authorization server for the primary device and used by the device when it makes the token request. |
client_id | Identifier for the primary device, assigned when it registered with the authorization server. |
The client ID and device code are used by the authorization server to associate the polling request with the primary device’s initial authorization request. The primary device should make polling requests no more frequently than the number of seconds specified in the interval parameter from the authorization server response. The device code and interval parameter are shown in Table 5-6. The primary device continues polling while the user interacts with the authorization server.
If the user has not yet completed the interaction, the client device will receive either an “authorization_pending” status or a “slow_down” status. The slow_down status indicates the client device should send subsequent polling requests less frequently. If the user does not approve the request, a status of “access_denied” will be returned, and if too much time passes, a status of “expired_token” may be returned, indicating the device code is no longer valid. These error codes are in addition to the general OAuth 2 error responses for conditions such as invalid requests, client IDs, grants, grant_types, and scopes or unauthorized requests.
When the user successfully completes the interaction on the secondary device to authenticate and authorize the access request, the primary device’s next polling request will result in a success response with an access token and, optionally, a refresh token as described in Table 5-4. The primary device can then use the access token to make an API call on the user’s behalf, as described in the following section.
Calling an API
Once an application receives an access token via one of the grant types described in the previous sections, it can call the resource server, sending the access token with its request. OAuth 2.1 specifies that an access token must be sent in either the HTTP Authorization request header or HTTP request payload. OAuth 2.1 specifically prohibits the access token from being sent in a URI query parameter.
A drawback with a bearer token is that it can be used by anyone that possesses the token. If an access token is stolen, an unauthorized party could use it to make a request to the API for which the token was issued. OAuth 2.1 recommends several measures, including short-lived access tokens, to mitigate the risk of access tokens being captured and used in an unauthorized manner. These are discussed in the “Token Usage Guidance” section later in this chapter.
Refresh Tokens
As mentioned previously, access tokens have an expiration. When an access token expires, an application could make a new authorization request, but with short-lived access tokens, this could result in frequent consent requests for users which would be cumbersome. OAuth 2 defines an alternative approach that involves another type of token called a refresh token. Authorization servers may, at their discretion, return a refresh token along with an access token. If an application receives a refresh token from an authorization server, it can use it to obtain a new access token when a previous access token expires. The use of a refresh token to obtain a new access token does not require user interaction, so an application can use a refresh token to obtain a new access token when the user is offline, which facilitates ongoing API access from native mobile applications.
OAuth 2 does not include a mechanism for applications to request refresh tokens, leaving the issuance up to authorization servers. The handling of refresh tokens may therefore vary across individual authorization servers. Some issue refresh tokens automatically, and others expect an application to explicitly request a refresh token via a proprietary mechanism. (The OIDC specification, covered in the next chapter, includes a mechanism for an application to request a refresh token for one specific use case.) The documentation for your chosen authorization server should explain the implementation-specific details for refresh tokens.
The access token will be returned in a response similar to that described in previous sections. The scope parameter is optional and, if used, must be equal to, or lesser than, the scope in the original authorization request, and the client credentials passed must be those of the application which made the original authorization request.
The use of refresh tokens applies primarily to authorization flows where a user is the resource owner. There is no need for a refresh token with the client credentials grant because an application can simply request an access token programmatically at any time, without a need for user interaction.
In addition to the basic mechanics of using access tokens and refresh tokens, there are several usage guidelines which we’ll cover in the next section.
Token Usage Guidance
Access Tokens
An access token is intended to be consumed by a resource server API. An application should not depend on using data in the access token (in the absence of proprietary extensions). Depending on the authorization server implementation, the format of an access token may be an opaque token or a JSON Web Token (JWT) as defined by the JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens.xv In the case of an opaque token, a resource server calls the authorization server’s token introspection endpoint to obtain the relevant information associated with the token. In the case of a JWT, the token is self-contained and a resource server can view the JWT attributes in the token. In either case, a resource server that receives an access token must validate it before processing the request it accompanies. The process for validating a token may vary by authorization server implementation.
Access tokens have an expiration time, and in general, it is recommended that access token duration be short-lived and a new access token obtained only when needed, if the previous access token has expired. It may be tempting to automatically refresh an access token as soon as it expires, but in keeping with the principle of least privilege, it is better to only refresh an access token when it is needed, rather than always keeping a current access token on hand. The access token expiration should be determined based on the sensitivity of the resources to be accessed.
Though access tokens have an expiration, they are not one-time-use tokens. Access tokens can be cached, for a period of time less than or equal to their expiration, as a performance optimization. Caching access tokens can also reduce the risk of hitting rate limits via excessive calls to an authorization server.
An access token must have been granted the appropriate scope of privileges for an application’s API calls. This should not, however, encourage the use of overly broad scopes, such as “do:anything” to avoid the work of designing an appropriate set of scopes. Applications should follow the security principle of “least privilege” to request access tokens with the minimum scope needed for a particular scenario. For example, a document viewer application that doesn’t provide editing features should only request a scope such as “get:documents” rather than scopes that would allow modifying or deleting documents.
Scopes should typically be used to model the coarse-grained privileges that an application can request of an API on a user’s behalf, such as “get:documents” rather than granular privileges involving specific resources. Baking specific resources into scopes can cause the number of scopes to become unwieldy to administer as the number of resources grows. In an enterprise scenario, baking user profile attributes or organization attributes used for access control into scopes will result in rework when the inevitable reorganizations occur. In addition, when the scope parameter is sent via URL, it can hit a length limitation. Additional options for authorization and access enforcement will be discussed further in Chapter 8.
Where possible, applications should request access tokens restricted to a particular resource server via a “resource” or “audience” parameter. This can prevent an access token issued for one resource server from being used at another resource server. Narrowing down the scope and intended recipient of the token can reduce the possibility of an access token being abused.
Refresh Tokens
Refresh tokens provide a convenient way for applications to obtain new access tokens. This facilitates the use of access tokens with a short duration, which minimizes risk if an access token is compromised. However, the use of refresh tokens introduces a different risk, namely, the risk of a stolen refresh token. Refresh tokens are sensitive credentials because they can be used to obtain access tokens. Applications must therefore protect and securely store both access tokens and refresh tokens. Applications should utilize the secure storage options available with their underlying platform when storing such tokens. At the time of writing, secure storage for single-page applications executing in browsers is limited. This means that use of static, long-lived refresh tokens is problematic, especially for public clients that lack mechanisms for securely storing sensitive tokens.
There are solutions to reduce the risk of compromised refresh tokens. The OAuth 2.0 Threat Model and Security Considerationsxvi document proposed the notion of refresh token rotation to detect if a refresh token has been stolen and is being used by two or more clients. This scheme has the authorization server return a new, single-use refresh token with each access token renewal request. If a refresh token is stolen and used twice, once by the legitimate client and again by a second, malicious client, the authorization server is supposed to detect it as an anomalous situation and invalidate the refresh token.
Another approach is the use of sender-constrained tokens, which can be used with both access tokens and refresh tokens. With this approach, the authorization server binds a token it issues to the authorized client application which requested it. If an unauthorized client application steals a token and attempts to use it, the authorization server or API will detect that the client attempting to use the token is not the client to which the token was issued. Several approaches for sender-constrained tokens have been defined. We will describe two methods. At the time of writing, it is not yet clear which approach(es) will become widely adopted.
One approach for sender-constrained tokens leverages Mutual-TLS. For this scheme, a client application authenticates to an authorization server using Mutual-TLS authentication, so that the authorization server can bind an access or refresh token to the client certificate used in the Mutual-TLS authentication. When the client wants to use the token, it must authenticate to the resource server, again using Mutual-TLS, proving that it possesses the private key associated with the certificate bound with the token. This scheme is defined in the OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens specification.xvii This specification has moved out of draft status but may result in a confusing user experience in some cases, if users are prompted to select an appropriate certificate to use.
Another scheme for sender-constrained tokens is defined in the draft (at the time of writing) OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP) specification.xviii With DPoP, when a client application sends an authorization grant or refresh token to get an access token, it creates and cryptographically signs a JSON Web Token (JWT). This token, called a DPoP proof JWT, includes the public key that corresponds to the private key used to sign the JWT. The client application includes the DPoP proof JWT in its request to the authorization server. The authorization server responds with an access token that includes a hash of the public key from the request. This binds the token to the public key. When the client application makes a request to the resource server, it sends the token, bound to the public key, and also sends another DPoP proof JWT demonstrating that it has possession of the original signing material. DPoP is currently being actively developed and we expect it will be adopted in the future.
OAuth 2.1 specifies that authorization servers must use either refresh token rotation or sender-constrained refresh tokens (bound to a particular client) with public clients to mitigate the risk of compromised refresh tokens. At the time of writing, it is not yet clear which of these solutions will become widely adopted and how long it will take. Check the documentation for your OAuth 2 provider for details on support for refresh token rotation and/or sender-constrained tokens.
Confidentiality and Integrity
The protocol interactions we have described in this chapter assume the use of a suitably up-to-date version of Transport Layer Security (TLS) between the application and the OAuth 2 authorization server, between the application and the resource server, and for interaction between the resource server and authorization server, if any. The OAuth 2 specifications state that authorization servers must require the use of TLS for requests to the authorization and token endpoints and that applications should enforce the use of TLS for the application callback. Further security implementation guidance can be found in the Security Considerations section of the OAuth 2.1 Authorization Framework document.xix
Applications must take suitable measures to ensure the security of access tokens and refresh tokens. Applications must perform all token validation checks recommended by their authorization server as well as a TLS certificate check when calling the resource server to ensure a request is sent to the correct resource server. Applications must use secure storage when storing sensitive tokens and take care to prevent leakage of such tokens. In addition, secure coding practices must be used, including implementing measures against attacks such as Cross-Site Scripting (XSS) and Cross-Site Request Forgery (CSRF), as applicable for the type of application.
Token Revocation
Applications should revoke refresh tokens and access tokens if possible, when they are no longer needed. The OAuth 2.0 Token Revocationxx specification defines a mechanism for clients to request the revocation of access tokens and refresh tokens. The ability to revoke access tokens, however, is not a mandatory feature, so some authorization servers may not support it. You’ll need to check the documentation for your OAuth 2 provider to determine support for revoking tokens. Additional discussion of token revocation with respect to logout is discussed in Chapter 13.
Further Learning
The preceding sections covered an introduction to how an application requests API authorization via OAuth 2. We realize it may seem like a lot to learn. An SDK may abstract and simplify the OAuth 2 interaction for you, and we recommend checking for the availability of SDKs for your platform. We should also note that it is beyond the scope of this chapter to cover every application implementation requirement mentioned in the specifications as they vary by application scenario. Application implementers should review the specifications for the latest version of implementation requirements for their type of application as well as guidance from any SDKs used.
Advanced Use Cases
There are additional, more complex use cases for which additional parameters and extensions to the core protocol have been advanced, such as the “OAuth 2.0 Token Exchange” specification.xxi It is beyond the scope of this book to provide sufficient guidance for how to implement such use cases securely, so we will only mention that there is a lot more to explore and learn about. We hope that this introduction to OAuth 2 prepares and encourages you to explore additional use cases and extensions in the future.
Summary
The OAuth 2 protocol enables an application to obtain authorization to call an API on either a user’s behalf or on its own behalf. This eliminates the requirement for users to share their credentials with the application. It also provides the user greater control over what the application can do and a limit on the duration of API access. The user can revoke API access for an individual application without impacting the ability of other applications to call the API on their behalf. Once you have an application authorized to call an API, you’ll want to authenticate users to that application, which is covered in the next chapter.
Key Points
OAuth 2 enables applications to request authorization and obtain an access token to call resource server APIs.
With OAuth 2, a user has control over API authorizations for applications.
Scopes can be used to control the access an application has when calling an API.
The original OAuth 2.0 specification defined four authorization grant types but two of these were removed in OAuth 2.1.
The OAuth 2.1 specification removes the implicit authorization grant type as it is no longer needed and can expose an access token to potential compromise. The authorization code grant type with PKCE should be used instead.
The OAuth 2.1 specification removes the resource owner password credentials authorization grant type as it exposes user credentials to client applications.
The authorization code grant type with PKCE can be used by traditional web applications, public applications, as well as native applications.
The client credentials grant type is for API calls where the application owns the requested resource.
The Device Authorization Grant type is an extension defined to enable flows involving client devices that lack the capability needed for user interaction to authenticate and authorize requests.
A refresh token is used to obtain a new access token when a previous access token has expired.
Refresh tokens should be sender-constrained or employ a refresh token rotation scheme.
Applications must take measures to secure access tokens and refresh tokens.
Applications must use a suitably up-to-date version of Transport Layer Security (TLS) for communications with an OAuth 2 authorization server.
Notes
- i.
- ii.
- iii.
- iv.
- v.
- vi.
- vii.
- viii.
- ix.
- x.
- xi.
- xii.
- xiii.
- xiv.
- xv.
- xvi.
- xvii.
- xviii.
- xix.
- xx.
- xxi.