theCodingInterface

OAuth 2.0 and Open ID Connect Cheat Sheet

By Adam McQuistan in Security 03/26/2022 Comment

Introduction

This article is a collection of key terms and concepts surrounding OAuth 2.0 and Open ID Connect (OIDC) authentication and authorization that I've found useful often referring back to as a quick and handy reference.

Example OAuth Request / Response Scenario

The below diagram depicts a example I made up to demonstrate how different OAuth concepts work to perform authentication and authorization.

In this example there are two distinctly separate OAuth 2.0 protected systems at play. A Weather Dashboard on the left and a Weather Data Provider on the right.

The Weather Dashboard contains a modern browser based Single Page Application (SPA) which integrates with Authorization Server A that also happens to be an Identity Provider with Single Sign On (SSO) using Open ID Connect (OIDC) that a user would sign in with. Once a user signs in via the paired interactions of the SPA frontend application partnering with the IdP Authorization Server A the SPA gets an ID Token, Access Token and Refresh Token (Tokens A) from the Authorization Server A. The SPA frontend packages Access Token A in a HTTP request to the Weather Dashboard's backend Weather Aggregation Service (resource server A). The Weather Aggregation Service (resource server A) would download and cache the public key of the JSON Web Key Set (JWKS) from the Authorization Server A that is part of the keys used to sign the issued Token A. This public key from Authorization Server A is used by the Weather Aggregation Service (resource server) to validate they tokens passed from the SPA application.

The External Weather Data Service is a external data provider the Weather Dashboard collects data from to aggregate and displays in the SPA application. The Weather Aggregation Service (resource server A) would need to be deployed with a Client ID (client B) and Client Secret (client B) issued from the Authorization Server B in order to make a request to Authorization Server B to obtain an Access Token (Access Token B) which it would then package in a HTTP request to the Weather Data Service (resource server B). This is an interesting duality where the Weather Aggregation Service (resource server A) plays both the part of being a resource server in the Weather Dashboard but a Client to the Weather Data Service.

There are several important terms used in the explanation of the example just described such as Client, Application, Resource Server, Authorization Server, and a few different Tokens. All of these terms are explained in detail below.

Key Concepts for OAuth 2.0, OIDC, Authentication, and Authorization

Authentication (authn) is the act of proving the identity of user wishing to use a service by presenting uniquely identifying credentials.

Authorization (authz) is the act of determining whether a user (either authenticated or unauthenticated as in the case of an anonymous user) is allowed to obtain information or perform some action.

Client is a specific application or piece of software with a desire to access the protected data or actions of a resource server. In this context a client service requesting to use the protected resource may or may not be associated with a user's identity and is instead a generic application making a request that requires credentials to use a service for example a weather dashboard could be a client calling a weather forecast API requiring authentication for enforcing request rate limits.

Application is a specific type of client that obtains identity and/or access tokens from an authorization (or Identity Provider) server after a user supplies authentication credentials to the authorization (or Identity Provider) server. The application would then use the identity and/or access tokens supplied by the authorization (or Idenity Provider) server and pass them in subequent requests to resources servers (aka microservices or some web service) that will validate the identity and/or access tokens with the authorization server to ensure the tokens are legitamate and indicate the client or user associated with the tokens have permissions to request the resource server's data or exposed behaviors.

Resource Server is an API, Web Service, or Microservice that a client/application wants to access to gain the benefit of the protected data or behaviors provided by the resource server.

Resource Owner is the entity such as a user, company, organization, or government that owns data or behavior supplied by a resource server.

JSON Web Token (jwt) is a standard format for transmitting user or client information and capabilities securely encoded in a JSON object. A JWT consists of three distinct sections of header, payload and signature all base64 encoded and separated by periods. For example, headerdata.payloaddata.signaturedata (again, these sections are base64 encoded).

header is a JSON data structure that contains key / value entries describing how the JWT is constructed such as its type (JWT) and the cryptographic algorithm that was used to encrypt the token
Payload is a JSON data structure that contains key / value entries of claims describing the entity the JWT represents such as the user or client making the request. There are standardized claims such as iss (issuer), sub (subject), exp (expiration time), aud (audience) and others along with custom claims defined and used to transmit application / resource server specific data.
Signature is final section of the JWT obtained by cryptographically signing the encoded header and payload sections using a secret and the algorithm specified by in the header section.

Access Token is a specific token provided by an authorization server and used by a client / application to communicate with a resource server which gives the client / application permissions to access the data or behavior protected by the resource server on behalf of the resource owner. Access tokens usually have a life time of 5 mins to a day or two.

Types of Access Tokens

Bearer Token
JWT Token
Opaque Token

Refresh Token is a specific yet optional token provided by the authorization server and used by the client / application which can be used to request a new access token near the end of the access token's life time to reduce the need or frequency of the end user needing to provide credentials to be passed along or given to the authorization (or Identity Provider) server. Refresh tokens usually have a life time significantly longer than an access token such as 1 to 30 days.

Client ID (sometimes called App ID) is an identifier used to identify a client app with a authorization server and is initially created by the authorization server before the client application can interact with it.

Client Secret (sometimes called App Secret) is a password like string used to verify the client application with an authorization server that initially created the secret and required before the client application can interact with it.

Identity Token is a specific token provided by a special authorization server used with OIDC called a Identity Provider. This token contains claims about the identity of the user such as their name, email, address, phone number and others.

Open ID Connect (OIDC) is an extension of OAuth 2.0 which provides authentication and Single Sign On (SSO) functionality by returning an ID Token from the Authorization Server and is associated with the request scope of "openid". IODC Authorization servers are often referred to as Identity Providers (IdP).

Scopes are specific granular permissions the client / application wants like to access user profile data or the ability to perform actions on behalf of the entity (aka user, company, etc...) interacting with the client / application. Scopes often relate to the concept of roles or grants used by different software frameworks such as Spring Security.

Claims are specific peices of information about the entity represented by the tokens supplied by a authorization server. These information claims represent specific information such as a users name or when the token was issued for a user.

Consent is the result of the Authorization server taking the scopes the client / application is requesting and the Authorization Server verifying (aka obtaining consent) fromt he end user / resource owner to tive the client / application such permissions for data requested or actions to be performed.

OAuth 2.0 Grant is synonomous with consent and is the explicit authorization given ("granted") to the client / application by the resource owner (user, company, etc...) such as "authorization code" or "client credentials" and each OAuth grant has a corresponding flow.