OAuth 2.0 Concepts & OAuth Flows

Topics Covered
OAuth 2.0 Concepts
OAuth 2.0 Actors
3-Legged Authorization Grant Flow
2-Legged flow
PKCE Flow

OAuth 2.0 Concepts

This story/article will theoretically explore the concepts, artifacts, and various OAuth flow actors and how these artifacts combine to protect resources. The principle behind OAuth flow is the token retrieval and the use of that token to access a resource.

OAuth 2.0 and OIDC flow falls under the federated Single Sign on (SSO) protocols.

What is a federated SSO? Federated SSO is accomplished with an identity provider (credential store) external to the service provider’s (any digital application offering) boundary. The protocols that support federated SSO are SAMLv2.0, OAuth v 2.0 and the identity-based OpenID Connect (OIDC) protocol.

The OIDC protocol builds on top of the OAuth 2.0 framework. OAuth is used only for authorization when a user needs to access a resource. The OIDC protocol asserts an identity and validates authenticated user claims. The identity assertion and validation happens through the user and token endpoints.

Access Managers vendors use proprietary standards implementation but follow the OAuth/OIDC frameworks.

Different Actors in OAuth 2.0 Echo System

The actors in the OAuth flow play specific roles. These artifacts provide the framework for OAuth flow . Different APIs are used for OAuth artifacts creation. The various OAuth actors are:

Clients

The clients register with the access server and interact with the OAuth service provider to gather the scope and token information and send it to the end application. The client could use an OAuth module to interact with the OAuth service provider. The applications that are protected by OAuth protocols interact with OAuth clients and OAuth resource servers.

Resource Owners

The resource owner owns the resource. The resources are hosted on the resource server. The information required to protect the resource is defined by the resource owners. A website hosting photos or a site allowing users to update content are examples of resources. When the user requests a resource, the agent protecting the resource will redirect the user to an OAuth Service provider for authentication. The user provides creds. and the consent for the requested scope. The different scopes can be read, write, update etc and could include the profile attributes of the user stored in the repo.

Resource Servers

The resources server hosts the resources. Usually, the resource server and the authorization server are the same. In the case of Oracle Access Manager or OpenAM, most of the authorization servers and the resource servers could be the same instance. The resource can be configured using the access servers console.

Authorization Server

The authorization server generates the access code once the user is successfully authenticated.

A client application requests the scope (profile attributes) on certain conditions. The attribute should be allowed access by the resource owner, before the client can use it.

OIDC provides an identity assertion layer on top of the OAuth 2.0 authorization layer. The tokens are key to the verification and referencing of user identity and authorization. The underlying model of communication for both OAuth and OIDC is the REST framework. The interaction data model of the APIs are JSON-based token name, value pairs.

In the following sections, we will see how all these actors fit together and play their part. In the subsequent posts you configure OpenAM to use OAuth 2.0 flow.

Client Credentials & Token

OAuth 2.0 features are available for web-based clients and are based on client credentials (secret), username /password. The key piece of this interaction is that the user accesses the resource, without exposing their credentials to the resource servers, which hold the resource. The credentials are submitted to the authorization server which acts as an intermediary that verifies the credentials and provides a token for the resource server to validate with the authorization server.

In some cases, the resource server and the authZ server will be the same running instance.This access token has a validity period and can be used to access multiple pre-configured resources for the OAuth Scope. The user can request an optional refresh token to refresh the access token when the initial access token has expired.

OAuth Authorization flow

The OAuth flow has two main variations, the 3 legged flow and 2 legged flow:

1. In the three-legged multiple-step process, the application request is sent to the resource owner to authenticate with the authorization server, the next step is for the resource owner to provide consent by clicking on an allow button or a deny button on the consent screen. If the user clicks the deny button, the token is not issued and the flow stops. If the user clicks the allow button , then the token flow continues and an access token is given.
2. The two-legged flow, the consent is removed out of the flow and allows the user to access the resource based on the pre-configured scope. In this case, the authz server gives the token without having the interaction with the resource owner. This works well when the setup between the client application and the resource owner is confidential with an agreed trust model.
3. The third flow is the PKCE Flow for less secure web applications or devices.

Various OAuth 2.0 Flows

3 Legged Authorization Grant Flows

The different authorization grants defined are :

Authorization Code grant

The 3 legged authZ grant flow has the following actors :

1. User Agent (Browser acting in favour of Resource Owner User)
2. Resource Server (That host the resource)
3. The AuthZ server which accepts the credentials, code grant and generates the access token.
4. The resources itself that need access.

In the 3 legged flow, the first step is for the authZ server to provide the login screen to the user agent browser for the user credentials. The different authN schemes are used to validate the credentials. Once the credentials are verified, then the request for consent is presented to the user. The user has to provide the consent or deny.

In the flow, there are certain artifacts that are mandatory to make this flow a success.

In this flow, the access token is obtained by the client for the exchange of client credentials & authorization code. The code flow is a prerequisite for 3 legged OAuth flow. In this flow, the access to the resource is given in return to the access token and the access token is given by the authorization server on successfully providing the authz code and the required artifacts. The OAuth protocol is mostly used where access is required. That access has to be configured using OAuth client and service provider before the actual interaction will happen.

In this grant type, the server generates an URL and redirects to the user to get the proper authorization. In the URL, the query string will have the following parameters:

1. Scope — defines the scope of action, the user has to approve. The scope values could be created, read or updated. The scope would include the profile attributes the client is requesting.
2. response_type= code ; this is used for authz code Grant type, indicating the application is initiating the authz grant code.
3. Client_id= The unique identifier for the application, this value is generated when the developer registered the application.
4. State — A unique random string, (like the nonce)which does not change and is usually used to identify the original request. This helps prevent the CSRF (Cross Site Request Forgery (CSRF) attacks.
5. Redirect-URI : The response URL where the user has to be sent, after receiving approval.

The authz code is used by web applications and any applications. The user is presented with the scopes(user profile attributes that are shared), which will be shown on the browser, the user has to approve the scope.

Once the user approves the scope, the user gets redirected to the redirect_URI with the authorization code (short-lived code, lasting maybe 10 mins max). This grant code is used by the client to get the access_token from the authz server to access the resource.

Access token flow:

Once the client has the authorization code, a new request is generated to get the access token. The access token request has the following parameters. It is a POST request to the authz servers token endpoint with the following parameters:
grant_type=authorization_code — This token endpoint recognizes the application is using the Authorization Code grant type.
code — The authorization code received from the original scope request.
redirect_uri — The redirect URI that was used in the original code request. This is an option value.
client_id — The application’s client ID, same as the one used in the original request.
client_secret — The application’s client secret, ensures the request is a valid request with the original authz code and is not intercepted by any potential attacker.

OAuth 3 Legged Grant Flow

The 3 legged flow, Resource Owner enters his credentials and explicitly grants permission to the client which needs access to the resources that are protected by the OAuth Resource Servers.

The OAuth servers which can be any access management servers, validate the credentials of the user and present the consent form, so that the user can either approve or deny the consent.

The response of the consent that is approved or denied is registered and the user is not asked for consent again in the same flow.

The actors are Resource owner (User), the client app (either web or web service based app), the resource server (that hosts the resource) and the authorization server (any access server).

• The flow starts with a client which needs access to a resource, invokes the authz endpoint. In this request, the client embeds client ID (identifier), the redirect URL to which the authz server will redirect the browser (user agent ) and very importantly the scope, the client request.
• The oAuth server requests the resource owner credentials to proceed with the next step of user authentication. The access manager product supports a lot of different authN modules /schemes and based on the preconfigured authentication module, the login form is displayed.
• The user(RO) enters the credentials (usern/pass), and submits it to the authz server. The authz server validates the creds and on success returns a request token to the browser/ client.
• Based on the consent config, the oAuth authorization server displays the consent form.
• The RO approves or denies the scope in the consent. Based on the agreed scope, the OAuth server sends an access code to the client.
• The client now requests the access token, using a POST request sent to the access token endpoint and attaches the access code sent by the OAuth server.
• If the flow requires validating client credentials, then OAuth server validates that as well. The request token is obtained after validating the access grant code, the scope, the redirect URLs and the unique identifier code
• The access token is presented to the resource server. The resource server sends the access token to the OAuth server for validation, received a success or failure response. On successful response, access granted.
• Lets look at the 3 legged flow diagram

OAuth 3- legged Grant code

OAuth 2.0, 3 Legged, authz code flow

The client needs access to the resource hosted by the RO on the authorization server. The interaction begins.

1. The useragent redirects the client to the Authorization server for authorization and session. The authz request is made with proper clientid, and client secret and the redirect URI.
2. The authz server does not find a valid session. Redirects the user to the resource owner.
3. The interaction between the AM and RO begins.
4. The RO inputs the credentials and provides the consent to access the resource
5. The temp authZ code and the redirect URL are send back to the client application
6. The client app presents the authz code, client secret and client ID to the authZ server token endpoint.
7. The server validates the code, access request, and the client credentials and issues a valid access token. And if requested a valid refresh token.
8. The client stores the access token and starts the SSO scenarios.

Why do we need an AuthZ code with 3 legs?

In this flow, there is a temporary code which has to be validated by the AuthZ server besides validating the client credentials . This provides an extra security and an additional layer of security.

The initial request has the following :

https://am.example.com:8443/sso/oauth2/root/authorize?client_id=abcClient \&response_type=code&scope=write,read&state=xyz321&redirect_uri=https://www.app.com:443/callback

OAuth 2-Legged Grant flow

OAuth 2.0, 2 legged, Implicit Flow

The interaction between the RO, Agent and the client happen without the grant code. The main difference between the interaction between the client and authz server is that, the extra step of access code grant is skipped.

1. The client using the agent, initiates the authZ flow for access token. In the request the client_ID, redirect URL and the requested response type is set.
2. The request for implicit flow, the respone_type is token.
3. The authZ server checks if the user session exists, the session doesn’t exist. The user is redirected to enter the credentials to authenticate.
4. The user enters credentials, authz server authenticates the credentials and sends the response.
5. The response_type was a token, the authZ server sent an access token instead of the code.
6. The client uses the access token and requests the resources on the resource server. The resource server validates the token with authZ server.
7. If the token is valid,the server gives access to the resource.

Sample Implicit flow request:

https://am.example.com:8443/sso/oauth2/root/authorize?client_id=abcClient&response_type=token&scope=write,read&state=xyz321&redirect_uri=https://www.app.com:443/callback

Authorization Grant code with PKCE (Proof key for code exchange )

Public client interactions use PKCE flow, in this instead of using client secrets that have the potential to be compromised, a code challenge is used. This flow suits Javascript applications or single page apps, where the secret cannot be stored securely. Using client secrets opens for CSRF attacks. PKCE flow provides an extra layer of security. The code verifier used in this flow is hashed and stored in the AuthZ server for future use.

This flow uses code_verifier (form parameter), code_challenge (query parameter) and the code challenge method used to retrieve the code. The code verifier is a dynamically generated one time credential. The decoded verifier can be used to verify the code challenge which was received by the access token.

The code verifier is a SHA 256 base 64 encoded string. For every interaction with the authz server, the code verifier is sent. The OAuth server compares the decoded code verifier with the code challenge. This flow is suited for untrusted, single page and mobile apps.

OAuth PKCE flow

curl — request POST — data “response_type=device_code” — data “client_id=abcClient” — data “code_challenge=hYstuuKKiiiLLkiuytfdgfdskgRRRE” — data “code_challenge_method=S256” — data “scope=write” “https://am.example.com:8443/sso/oauth2/realms/root/device/code"

This article discussed the concepts of OAuth2.0 protocol, the various actors that form the artifacts and the different type of flows like 3 legged, 2 legged and the PKCE flow. In the next article, we will configure and test one flow using OpenAM. Check https://iamblockc.medium.com/.