OAuth 2.0 and OpenID Connect commonly used terms explained

OAuth and OpenID Connect

OAuth (Open Authorization) is an open standard for API access delegation. Put simply, it’s a secure authorization protocols used to grant applications access to protected resources without exposing credentials.

OpenID Connect (OIDC) is an authentication layer (i.e. an identity layer) on top of OAuth 2.0. Client applications can use it to verify the identity of a subject (usually a user) based on the authentication performed by an authorization Server. It also provides basic profile information.O

Authentication

Authentication is the process of identifying an individual e.g. using a username and password. This basically involves checking whether a user exists and determining who this user is i.e. associating credentials with an identity. Or in other words authentication answers the question “who one is”. OAuth is a specification for authorization and is not an authentication protocol but is used as a basis for authentication protocols like OpenID Connect.

Authorization

Authorization is the process of giving a subject permissions to access resources in a certain way.

OAuth 2.0 Roles

OAuth defines the following roles:

Resource Owner
Client Application
Resource Server
Authorization Server

Resource Owner

The resource owner is an entity which can grant a client application a scoped access to a resource. It can be a person (usually the end-user) but can also be a machine.

Client Application

A client application is an application which accesses protected resources on the behalf of the resource owner.

Resource Server

The resource server manages access to a protected resource, allowing access based on access tokens. It is also often called an API server. The protected resources can e.g. be the profile or personal information of a user.

Authorization Server

The authorization server issues access tokens to authenticated client applications when permissions for the access are granted by the resource owner. This is the “OAuth2” server.

OAuth 2.0 Role Interactions

Tokens

There are 3 types of tokens used when working with OAuth2 and OpenID Connect. Additionally, an authorization code is also defined.

The ID token is defined in OpenID Connect on top of the tokens defined in OAuth2
The access token is the main token defined in OAuth2
The refresh token is used, well, to refresh a token
The authorization code is not a token in itself but can be used to get an access token

ID Tokens

ID Tokens are JSON Web Tokent (JWT) introduced by OpenID Connect. These tokens identify a user and contain user’s authentication information. They contain three parts:

a header
a body
a signature

In the token, each of these parts is encoded using Base64Url and concatenated using a “.” (dot) between them:

Base64Url(header) + “.” + Base64Url(body) + “.” + Base64Url(signature)

The body of the token contains a series of claims which provide data about the subject being identified by the token. The OpenID Connect specification doesn’t specify which claims have to be present in which context but does define “standard” claims (with registered claim names) and allows the use of custom claims. The registered claim names are:

iss: it’s the issuer of the token.
sub: this claim identifies the subject for which the token was issued. It is at least unique within the scope of an issuer.
aud: this claim identifies the audience for this token. This is the intended recipient(s) for this token. If an entity is processing this token does not identify itself as part of this audience, the token will be rejected.
exp: this is the expiration time of the token. An entity processing this token should reject it once the expiration time is reached.
nbf: this is the “not before” claim i.e. it defines at which point in time this token will be valid from. An entity processing this token before this point in time should reject it.
jti: this is an identifier for this particular token which should be unique per issuers and only have a low probably of not being unique globally.

Some claims are always added to the ID token by the authentication server and some claims depend on the scopes requested by the entity requesting the authentication.

Since the ID tokens contain privacy relevant data about subjects being identified, they should be kept confidential and access tokens should rather be used to access resources i.e. use the ID tokens to identify subjects and get data/metadata regarding the subject and access tokens to access resources / APIs.

This is how an ID token could look like:

{
  "https://benohead.com/country": "Germany",
  "https://benohead.com/timezone": "Europe/Berlin",
  "email": "henri.benoit@gmail.com",
  "email_verified": true,
  "iss": "https://auth.benohead.com/",
  "sub": "5b1789917b944931f4021e61",
  "aud": "q580zCRvynSeIg3uXCChcSRlYtNKSUPe",
  "iat": 1530800423,
  "exp": 1530836423
}

Access Tokens

Access tokens allow a client application to access a protected resource and defines the scope of this allowed access. This token is provided by the client application to the resource server when accessing the resource e.g. as an HTTP header. Just like the ID token, the access token has a limited lifetime which is defined when the authorization server issues the token to the client application. Since it allows access to protected resources, it must be kept confidential as much as possible although this is not always possible especially when a web browser is involved.

This is how an access token could look like:

{
  "iss": "https://auth.benohead.com/",
  "sub": "5b3cd37722c8f80eecd338e5",
  "aud": "https://benohead/api/dummy/",
  "iat": 1530802106,
  "exp": 1530888506,
  "scope": "read update delete create"
}

Note that in case the authorization server is also the resource provider (so if the audience matches the authorization server), you might also get an opaque access token which is just a string without any further meaning and which cannot be decoded. The authorization server can then map this string to permission on its own protected resources.

Refresh Tokens

Refresh Token are tokens containing information required to obtain a new ID token or access token. It is usually used to get a new token after the previous one expires. It is usually more secure to have short lived access tokens combined with refresh tokens, since it allows the authorization server to refuse to issue a new access token based on the refresh token in case the token has been compromised but still allow renewing the token in case access to a resource is required for a longer time. Without refresh token (and with long lived access tokens) a resource provider would need to query the authorization server to see whether the long lived access token is still valid. You can skip it when using short lived access tokens.

As an alternative to using refresh tokens, you could get a new access token with credentials every time a short lived access token expires. But there has a drawback: If you get the access token with user credentials (additionally to client credentials), you will need these user credentials every time your token expires (while you wouldn’t need the user credentials, just the client credentials, when using a refresh token).

Authorization Codes

Authorization codes are codes returned to unsecure clients. These client can then exchange them with an access and/or ID token in a more secure way.

They are used in the Authorization Code Grant Flow which is a flow where the client is typically a browser which receives an authorization code from the authorization server and sends this to the web application which then interacts with the authorization server in the back-end to exchange the authorization code for an access token, a refresh token and/or ID token.

Scopes and Audiences

Scopes and audiences are used to handle multiple resource servers and multiple types of access permissions.

Audience

The JWT aud (Audience) Claim identifies the intended recipients of the token i.e. it allows an authorization server to issue tokens that are only valid for certain purposes.

An audience claim can either contain a list of strings (i.e. multiple audiences) or it can be a single string (i.e. there is only one intended audience). It does not matter if an audience value is a URL or some other application specific string.

Each recipient of such a token must validate that the audience specified in the token matches its own audience name. It must then reject any token that does not contain its own audience name in the intended audience. The authorization server which issues the token can only validate whether a token for this audience can be issued. It is the responsibility is the resource server to determine whether the token should be used or not. A resource server may choose to ignore the audience claim and accept any valid token.

So the audience claim is only useful if you want to issue tokens with different purposes (i.e. intended audiences) and if at least some of the APIs (resource servers) you are using are validating the audience claim.

Scopes

Scopes provide a way to limit the access to functionality provided by the resource servers. The client can request scopes to be provided in the issued access token. The authorization server can provide all requested scopes, some of them or even additional ones based on its internal rules/policies. The provided scopes are written in the scope claim in the access token.

So they basically act as permissions. Authorization servers also use them when getting the consent from the user (i.e. ask the user whether he really wants to provide the client application access to these specific scopes).

When the client then uses the issued access token to request access to a protected resource, the resource server will validate that the type of resource and the type of access match the scopes contained in the access token.

E.g. if your access token contains the scope claim “read:posts read:comments write:comments”, the resource server would allow an application presenting this token to have read access to the posts and read and write comments but not to create a new post.

OpenID Connect Scopes

The following scopes are defined in OpenID Connect:

openid: this is the basic OpenID scope requesting to return the sub claim uniquely identifying the user and which can be used in combination with the scope values below.
profile: requests the authorization server to provide access to the user’s profile claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.
email: requests the authorization server to provide access to the email and email_verified claims.
address: requests the authorization server to provide access to the address claim.
phone: requests the authorization server to provide access to the phone_number and phone_number_verified claims.

OpenID Connect Endpoints

OpenID Connect defines 2 endpoints which can be used to request one or more of the token types described above:

The Authorization Endpoint is usually an endpoint accessible with the URL <authorizationserver>/login or <authorizationserver>/authorize
The Token Endpoint is usually an endpoint accessible with the URL <authorizationserver>/token

In some of the flows described below (in the ones not requiring an authentication code), you might be connecting to either the authorization endpoint or the token endpoint (depending on you authorization server).

Additionally, it also defines the UserInfo endpoint which returns claims about the authenticated user.

The Authorization Endpoint

The authorization endpoint is an endpoint the user is sent to in order to:

get authenticated by any supported method e.g. with a username and password, an existing session cookie or a federated identity provider such as a social login, SAML provider or ADFS integrated system
issue a token to the client application (or deny it). Optionally, it will request a user consent (or issue a consent implicitly by using an internal policy)

The type of token being issued depends on the requested response type.

The Token Endpoint

The token endpoint can exchange a grant (e.g. an authorization codeprovided by the authorization endpoint) for a token. The grant supported as input are usually:

An authorization code
Client credentials i.e. a client ID and a client secret
A username and password
A refresh token

The UserInfo Endpoint

The UserInfo endpoint returns claims about the authenticated user. This is an OAuth 2.0 protected resource so you need to provide an access token to access it.

Here is a sample response from this endpoint:

{
	"sub": "1761101158623",
	"name": "Henri Benoit",
	"given_name": "Henri",
	"family_name": "Benoit",
	"preferred_username": "benohead",
	"email": "henri.benoit@gmail.com",
	"picture": "https://secure.gravatar.com/avatar/bde998b4b8e4b4fb259d80b5ac05d63d"
}

OpenID Connect Response Types

OpenID Connect defines an additional URL parameter called response_type. With this parameter, you can request different types of tokens to be returned. You can combine them by separating them by a space e.g. response_type=code id_token token.

id_token: if this response type is specified, the authorization server will return an ID token
token: if this response type is specified, the authorization server will return an access token
code: if this response type is specified, the authorization server will return an authorization code