Map of OAuth 2.0 Specs

24

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://tools.ietf.org/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://tools.ietf.org/html/rfc6750

The core spec doesn’t define the format of access tokens or how they can be used. Access tokens were a major point of contention in the early days of developing the core spec, and the result was that access tokens were taken out of the core spec entirely rather than having people compromise on undesirable tokens. However, in the time since then, most implementations have standardized on using Bearer Tokens. RFC 6750 describes the syntax and method for using Bearer Tokens to access APIs.

Threat Model and Security Considerations (RFC 6819)

https://tools.ietf.org/html/rfc6819

The Threat Model and Security Considerations document was written to provide additional guidance beyond what is described in the core document. 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.

Tokens

Token Introspection (RFC 7662)

https://tools.ietf.org/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.

Token Binding

https://tools.ietf.org/html/draft-ietf-oauth-token-binding

The Token Binding extension describes a technique for cryptographically binding a token to a client, to protect tokens from man-in-the-middle and replay attacks. Standard Bearer Tokens and authorization codes have no cryptographic connection to the client using them, which was a major change in OAuth 2 from OAuth 1.

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

https://tools.ietf.org/html/draft-ietf-oauth-native-apps

This document is more of a set of guidelines rather than protocol changes. In this document you’ll find recommendations for native applications and security recommendations unique to those environments. 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, which is described below.

PKCE: Proof Key for Code Exchange (RFC 7636)

https://tools.ietf.org/html/rfc7636

Public clients such as mobile and desktop apps lack many of the features of web apps that make the Authorization Flow secure. Web apps have the benefit of being accessed using an HTTPS URL, so the authorization server can be reasonably confident that it is redirecting the user’s browser to the genuine application after it generates the authorization code. Web apps are also able to utilize a client secret when exchanging the authorization code for an access token. Since mobile and desktop apps have neither of these features, the authorization server can’t be sure that it’s returning the user to the genuine app.

The PKCE extension describes a way for the app to first generate a secret that is used when requesting the access token so that an attacker that intercepts the authorization code can’t make use of the stolen code.

The PKCE extension is covered in more detail in PKCE.

Device Flow

https://tools.ietf.org/html/draft-ietf-oauth-device-flow

The Device Flow is an extension that enables devices with no browser or limited input capability to obtain user authorization. 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 input mechanism other than a few buttons.

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 Session Management

These specs are used to facilitate authentication and session management, neither of which are part of the core OAuth spec.

OpenID Connect

https://openid.net/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://www.w3.org/TR/indieauth/

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.

Token Revocation (RFC 7009)

https://tools.ietf.org/html/rfc7009

This document describes a new endpoint for authorization servers which 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 credentials associated with that session.

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

https://tools.ietf.org/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://tools.ietf.org/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://tools.ietf.org/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.

Enterprise

These specs support more advanced enterprise use cases.

Assertion Framework (RFC 7521)

https://tools.ietf.org/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 Assertions (RFC 7523)

https://tools.ietf.org/html/rfc7523

This spec describes how a JWT can be used to request an access token when there is an existing trust relationship with the client as described by the contents of the JWT. It also describes how a JWT can be used as client authentication for the core OAuth grants.

SAML Assertions (RFC 7522)

https://tools.ietf.org/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.