OAuth 2.0

Introduction

History

Previously we used

• XML
• SOAP
• SAML or WS-*

Now we Use

• JSON
• HTTP APIs
• OAuth and OpenID Connect

Credential Sharing

Previously we used to use credential Sharing. E.g. Problems with this are

• We can impersonate the use
• Issues around revocation
• Exposed user credentials

Cookies

Next solution was cookies but CSRF and XSRF attacks were common.

API Key

Next API Key, this works well accept for where the app has no backend. E.g. Single Page App.

• API Keys have no standard
• Expiration management

OAuth 2.0

Features include

• Authorization framework
• Built for HTTP APIs
• Scoped access (User defined what can be used)
• Delegation Protocol

Players include

• Protected Resource (Our API)
• Client (requesting application)
• Resource Owner (the user)
• Authorization Server

Here is the flow for OAuth 2.0
How the API trusts the access token is out of scope for OAuth but if is up to the Protected Resource to do this before sending the response.

Detail

Endpoints

The Protocol endpoint are either

• Authorization Handles all user interaction by the user agent
• Token - This endpoint is for machines only

Scope

A scope in OAuth is a permission to do something with a protected resource. E.g. access to API, Read/Write, Feature.

Grant Types

Types

There are five Grant Types

• Authorization Code Grant Type
• Implicit Grant Type
• Resource Owner Credentials Grant Type (Don't use)
• Client Credentials Grant Type
• Refresh Token Grant

See https://athiththan11.medium.com/oauth-2-grant-types-a-story-guide-582580a3c4c2 for more

Authorization Code Grant Type Flow

The Authorization Code Grant Type is the most commonly used grant type to authorize the Client to access protected data from a Resource Server.

Step 1 - Authorization Request

To make an Authorization request we send

• Response Type
• Client Id
• Redirect Uri
• state (optional)
• scope parameters (optional)

Step 2 - Authorization Response

This redirect to the Url in the request and returns

• code
• state (optionally)

Step 3 - POST Token Request

The parameters include

• Host (e.g. myserver.co.nz)
• Content Type (e.g. x-www-for-urlencoded)
• Authorization (e.g. Basic)

The POST body must include a body with

• grant_type=authorization_code
• code=authorization_code (from step 2)
• redirect_uri=https://client.example.cb

There are two forms of Basic Authentication

• RFC 7617 Base64(client_id + ":" + client_secret)
• RFC 67649 Base64(urlformencode(client_id) + ":" + urlformencode(client_secret))

Step 4 - Token Request Response

If successful we will get

• access_token
• token_type
• expiry (in seconds)
• scope (optional)

Implicit Grant Type Flow

The Implicit Grant Type is intended to be used by user-agent based clients (Example: SPA), which can’t keep a client secret because all of the application code and storage is easily accessible.

Step 1 Authorization Request

For the request we send

• response type
• client id
• redirect_uri
• state
• scope

The redirect is the main defense for abuse

Step 2 Authorization Response

In the response we receive in the Url fragment

• access token
• type type
• expiry (in seconds)
• state

Refresh Token Grant

Introduction

The Refresh Token Grant Flow is specially used to gain new access_token from the Authorization Server by providing the refresh_token to the Token Endpoint.

• Can be swapped for new tokens
• Allow for long-lived access
• Highly confidential
• User should be made aware that refresh tokens are being requested

Step 1 Authorization Request

This is similar to authorization code

• response type
• client id
• redirect uri
• state (optional)
• scope (optional)

A common scope used is offline_access which indicates the usage of this token.

Step 2 Authorization Response (token response)

The response will contain

• access token
• token type
• expiry (in seconds)
• refresh token
• scope

Step 3 Refresh Token Request (POST)

In this we send to the token endpoint a request with

• Host
• Authorization
• Content type

And parameters

• grant_type=refresh_token
• refresh_token
• scope

Step 4 Refresh Token Response

If successful we receive

• Access Token
• Token type
• Expiry (in seconds)
• Refresh Token
• Scope

Response Modes

The are three response modes

• Query String
• Hash Fragment
• Form Post (Recommended)

Errors

If there are errors the server may return

• error
• error description
• error url
• state

If this is the token endpoint they are sent in the post body otherwise in the query string. Usually with a 400 bad request.

Recommended Flows in OAuth 2.1

Here is probably the present.

Best Practices

Native Apps

Native Application or Public clients are apps which run on infrastructure not necessarily owned by the company. E.g. Web app, Mobile app and therefore they should not use the Native Flow. Native Applications

• Can
  • Make secure back channel requests
• Can't
  • Receive tokens via the browswer
  • Keep a secret (and be trusted)

Proof Key For Code Exchange (PKCE "Pixie")

This links the authorization request to the token request and is detailed in RFC 7636

Redirect URI Options

With the direct on a mobile there are three options list in order of preference

• Private-use URI Schema e.g. nz.co.bibble.linux:/callback
• Claimed https scheme
• Loopback device