The OAuth 2.0 Core Framework (RFC 6749) defines roles and a base level of functionality, but leaves a lot of implementation details unspecified. Since the publication of the RFC, the OAuth Working Group has published many additional specs built on top of this framework to fill in the missing pieces. Looking at the full list of specs the group is working on can be somewhat overwhelming. This chapter lays out how the various specs relate to each other.
Core Specs
OAuth 2.0 Core (RFC 6749)
https://datatracker.ietf.org/doc/html/rfc6749
RFC 6749 is the core OAuth 2.0 framework. This describes the roles (resource owner, client, authorization server, etc, described in more detail in Terminology Reference, several authorization flows, and several error definitions. It is important to remember that this is a “framework,” as there are many aspects left unspecified that you’ll need to fill out when building a complete implementation. Much of these details have been documented as extension specs.
Bearer Token Usage (RFC 6750)
https://datatracker.ietf.org/doc/html/rfc6750
Access token usage is defined in RFC 6750, although the format of access tokens isn’t defined here. This spec defines “Bearer Tokens”, which just means that it’s a type of token that can be used by whoever has the token with no additional information. The particular format access tokens take (random strings, JWTs, etc) is not relevant to OAuth clients so isn’t included in this spec. Only the Authorization Server and Resource Server need to coordinate on access token formats, so that is left up to the particular implementation or a future spec.
PKCE: Proof Key for Code Exchange (RFC 7636)
https://datatracker.ietf.org/doc/html/rfc7636
PKCE is an extension to the Authorization Code flow that adds a secure link between starting and completing the flow to prevent authorization codes from being used if intercepted.
PKCE works by the app first generating a new secret each time it starts the Authorization Code flow, and it sends a hash of the secret in the initial authorization request. The original secret is then required in order to exchange the authorization code for an access token, ensuring that even if an attacker can steal the authorization code, they would be unable to use it.
At the time of publication, PKCE was recommended for mobile apps, but it has proven to be useful even for JavaScript apps, and now the latest Security Best Current Practice recommends using it for all types of apps, even apps with a client secret.
Threat Model and Security Considerations (RFC 6819)
https://datatracker.ietf.org/doc/html/rfc6819
The Threat Model and Security Considerations document was written to provide additional guidance beyond what is described in the core RFC. Much of this document was added after major providers had real implementation experience. The document describes many known attacks, either theoretical attacks or ones that have been demonstrated in the wild. It describes countermeasures for each.
Everyone implementing an OAuth 2.0 server should read this document to avoid falling into traps that have already been explored and solved.
OAuth 2.0 Security Best Current Practice (Security BCP)
https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics
OAuth 2.0 Security Best Current Practice describes security requirements and other recommendations for clients and servers implementing OAuth 2.0. This is a new Best Current Practice around OAuth security, intended to capture experience gained from live deployments in the years since the first Security Considerations RFC was published in 2013.
This spec is also still in draft form, so will likely go through a few more changes before it is finalized as an RFC.
Some of the concrete recommendations in this draft are deprecating the Implicit flow and Password grant, and recommending that a new refresh token is issued every time one is used.
Tokens
Token Revocation (RFC 7009)
https://datatracker.ietf.org/doc/html/rfc7009
Token Revocation describes a new endpoint on the authorization server that clients can use to notify the server that an access token or refresh token is no longer needed. This is used to enable a “log out” feature in clients, allowing the authorization server to clean up any tokens or other data associated with that session.
Token Introspection (RFC 7662)
https://datatracker.ietf.org/doc/html/rfc7662
The Token Introspection spec defines a mechanism for resource servers to obtain information about access tokens. Without this spec, resource servers have to have a bespoke way of checking whether access tokens are valid, and finding out user data about them, etc. This typically occurs by either a custom API endpoint, or because the resource server and authorization server share a database or some other common storage.
With this spec, resource servers can check the validity of access tokens and find out other information with an HTTP API call, leading to better separation of concerns between the authorization server and any resource servers.
JWT Profile for OAuth Access Tokens (RFC 9068)
https://datatracker.ietf.org/doc/html/rfc9068
The JWT Profile defines a JWT-based format and vocabulary for access tokens based on the collective experience learned from several large deployments.
Mobile and Other Devices
These specs are written to enable support of OAuth on a wider variety of devices.
OAuth 2.0 for Native Apps (RFC 8252)
https://datatracker.ietf.org/doc/html/rfc8252
The intended audience for this spec is implementers of mobile apps or apps running on desktop devices, where interactions between the app and the browser are not as straightforward as in a browser-only environment.
In this document you’ll find security recommendations unique to the native application environment. It describes things like not allowing the third-party application to open an embedded web view which is more susceptible to phishing attacks, as well as platform-specific recommendations on how to do so. It also recommends using the PKCE extension.
Browser-Based Apps
datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps
OAuth 2.0 for Browser-Based Apps describes security requirements and other recommendations for JavaScript apps (commonly known as Single-Page Apps) using OAuth.
As of this publication, this document is still in draft form and is not yet an RFC. It is likely to go through some more changes before it is finalized. It has been adopted by the working group, which means people broadly recognize the need for this kind of guidance, although the specific recommendations inside have not necessarily yet been fully agreed upon yet.
This document is intended to complement the Native App Best Current Practice, addressing the specifics of a browser-based environment instead.
It recommends using the Authorization Code flow with PKCE instead of using the Implicit flow, and disallowing the Password grant by browser apps. It also provides a few different architectural patterns available to these apps.
Device Authorization Grant (RFC 8628)
https://datatracker.ietf.org/doc/html/rfc8628
The Device Authorization Grant is an extension that enables devices with no browser or limited input capability to use OAuth. You’ll typically see this on devices like the Apple TV where there is no web browser, or streaming video encoders where there is no keyboard.
The flow works by having users visit a URL on a secondary device like a smartphone and entering a code that is shown on the device.
The Device Flow is described in more detail in OAuth for Browserless and Input-Constrained Devices.
Authentication and Identification
These specs are used to provide applications with a user’s identity, which is not provided by the core OAuth spec.
OpenID Connect
Since the OAuth framework only describes an authorization method and does not provide any details about the user, OpenID Connect fills this gap by describing an authentication and session management mechanism.
We cover a brief overview of how OpenID Connect relates to OAuth 2.0 in OpenID Connect.
IndieAuth
https://indieauth.spec.indieweb.org/
IndieAuth is a decentralized identity protocol built on OAuth 2.0, using URLs to identify users and applications. This avoids the need for prior registration of clients, since all clients have a built-in client ID: the application’s URL.
We cover a brief overview of the authentication and authorization workflows of IndieAuth in IndieAuth.
Interop
In order to support creating completely generic clients that can work with any OAuth 2.0 server, things such as discovery and client registration need to be standardized, since they are out of scope of the core spec.
Authorization Server Metadata (RFC 8414)
https://datatracker.ietf.org/doc/html/rfc8414
The Authorization Server Metadata spec (also known as Discovery) defines a format for clients to use to look up the information needed to interact with a particular OAuth server. This includes things like finding the authorization endpoint, and listing the supported scopes.
Dynamic Client Registration (RFC 7591)
https://datatracker.ietf.org/doc/html/rfc7591
Typically developers will manually register an application at a service to obtain a Client ID and provide information about the application that will be used on the authorization interface. This spec provides a mechanism for dynamically or programmatically registering clients. This spec was derived from the OpenID Connect Dynamic Client Registration spec and is still compatible with OpenID Connect servers.
Dynamic Client Management (RFC 7592)
https://datatracker.ietf.org/doc/html/rfc7592
In the case that client information needs to be updated, this spec provides a mechanism for doing so programmatically. This spec extends the Dynamic Registration RFC 7591, but is considered experimental still.
High Security
There are a few extensions to OAuth that provide higher levels of security compared to the base profile. Some of these are part of the Financial-Grade API work being done in OpenID Connect as well.
Pushed Authorization Requests (RFC 9126)
https://datatracker.ietf.org/doc/html/rfc9126
Pushed Authorization Requests is a significant change to the OAuth flow to rely less on the front channel, by moving the start of the authorization code flow to the back channel instead.
JWT Authorization Request (RFC 9101)
https://datatracker.ietf.org/doc/html/rfc9101
JWT Authorization Request describes a way to encode and sign the authorization request parameters as a JWT instead of using plain query string components. This lets the authorization server be sure that a particular OAuth application initiated the authorziation request and the request has not been forged or tampered with.
Mutual TLS Bound Access Tokens (RFC 8705)
https://datatracker.ietf.org/doc/html/rfc8705
Mutual TLS Certificate-Bound Access Tokens describes a way to use TLS certificates for client authentication as well as issuing certificate-bound access tokens. This is one way implementers are improving the security of bearer tokens.
Experimental Specs
These are early drafts of some new specs that may end up becoming part of OAuth 2.0. These specs enable additional use cases, or provide better security. These are all still early drafts, so they may change significantly by the time you’re reading this, or may have been dropped entirely. These are some things to keep an eye on if you’re interested in keeping up to date with the latest developments in the space.
Rich Authorization Requests
https://datatracker.ietf.org/doc/html/draft-ietf-oauth-rar
Rich Authorization Requests describes way for apps to request permissions more fine-grained than the current OAuth “scope” mechanism can provide. This could be used, for example, to authorize a particular bank transfer.
DPoP
https://datatracker.ietf.org/doc/html/draft-fett-oauth-dpop
DPoP describes an alternative to Mutual TLS for issuing access tokens that are bound to a particular client. This version accomplishes that in the application layer rather than transport layer.
Enterprise
These specs support more advanced enterprise use cases.
Assertion Framework (RFC 7521)
https://datatracker.ietf.org/doc/html/rfc7521
This spec provides a framework for using assertions with OAuth 2.0. It defines a new client authentication mechanism and a new authorization grant type. As this spec is also a framework, it is only useful with one of the specific assertion types described below.
JWT Profile for Client Authentication (RFC 7523)
https://datatracker.ietf.org/doc/html/rfc7523
This spec describes how a JWT can be used for client authentication in place of a client secret. This method is more secure than using a shared client secret as the private key never needs to leave the client, and is instead used to sign a JWT.
SAML Assertions (RFC 7522)
https://datatracker.ietf.org/doc/html/rfc7522
This spec describes how a SAML Assertion can be used to request an access token when there is an existing trust relationship with the client. This can be used, for example, to integrate legacy SAML workflows with new OAuth 2.0 systems.