OAuth 2.0

OAuth 2.0 is an IETF standard which describes a protocol for securing APIs. A highlight of OAuth 2.0 is the ability for an end user to delegate some of their permissions on a service to a (potentially unrelated) application.

What problem is OAuth solving?

Without OAuth, an API service will often require that requests include end user credentials (e.g. a username and password) to authenticate access. An application wanting to access the service on behalf of a user must ask for their credentials and then impersonate them. This is a bad pattern:

• the user has no way to limit what the application does with their credentials
• the user has no way to revoke the application's access (without changing their password)

How does OAuth work?

With OAuth, an API service requires that requests include an access token which links to (or encapsulates) authorization data such as an associated end user, the scope of access, or a time limit. An application wanting to access the service (in its own right on on behalf of a user) must first obtain an access token from the authorization server associated with the API service.

An access token is obtained using a flow specific to the grant type. There are many different grant types defined for different use cases. These will be covered in other documents in this section.

As part of the access token request, the application can specify the scopes of access it wants. The Authorization Server can decide whether or not to grant some or all of the requested scopes (based on any logic it chooses). For some grant types, the Authorization Server may ask the end user to consent to the scopes that the application has requested. This gives the end user control (or at least visibility) of what authority is being delegated.

An access token will usually have a limited lifetime. Depending on the type of access token used, it may be possible for the user (or the service) to revoke the access token even before that time expires.

Access token format

Depending on implementation, an OAuth access token can be either:

• a random string of characters which indexes the grant (information about the granted access) in a data store held at the Authorization Server; or
• a signed token (usually a JSON Web Token) which encapsulates the grant information.

Random index

When the access token is an index, a service receiving the token can call an introspection endpoint on the Authorization Server to request the grant information associated with the access token. This information will include a status, indicating whether the token is active or inactive, and it may also include the associated user identity and the granted scopes.

Since the access token has no meaning without the associated grant data stored at the Authorization Server, it is possible for the access token to be centrally revoked by simply discarding this association.

JSON Web Token (JWT)

When the access token is a JSON Web Token, a service receiving the token can validate it and extract the data it contains without having to call back to the Authorization Server. This reduces network calls but at the cost of central control over revocation. An access token in the form of a JSON Web Token is valid until the expiry time specified in the token.