OAuth — orientation and terms

Aubyn Crawford
6 min readDec 28, 2020
Photo by Milan Seitler on Unsplash

This is a “primer” page for existing developers, to help orientate you when reading up about OAuth solutions.

You might notice that on this page (and the example pages), I’m trying to avoid some of the key terms set out in OAuth / OIDC. The reason for this, is to try and make OAuth more understandable in practice — this isn’t going to work for everyone, many developers will dive into the RFCs and pull out what then need straight away.

Common concepts to OAuth and OIDC

First I will cover off some of the “safe” terms and concepts that I prefer. I’m using the word “safe” here because these terms are unambiguous (not re-used) in different parts of the standards.

Flow

OIDC uses the term “Flow” more actively than OAuth. It describes the main use case / context, and it is important to understand how the choice of “flow” has massive impacts your real world implementation. In OAuth it uses the term “Grant” to distinguish between use cases, but confusingly the grant_type parameter is only used on the Token endpoint, and you start the sequence of events with a response_type parameter on the Authorize endpoint…

So, out of all the myriad of options, it comes down to two flows for me:

  • Authorisation code flow
  • Client credentials flow

(Although I am not the only one struggling to decide on a term — OAuth 2.0 has an extension for the Device Authorization Grant (RFC8628), which was originally “Device Flow”)

Legs

The term “legs” isn’t used enough! It tells you how many parties are involved in the journey. Two types:

  • Two legged — just a client and server
  • Three legged

Three legged involves a third server or endpoint — and provides a back-channel between the OAuth Server and your infrastructure. It should make any implementation impossible to break into:

  • That endpoint is pre-shared during configuration, so can’t be changed by the client
  • The endpoint has to exist and respond correctly to complete the user journey

The “flow” name doesn’t provide any hint of whether it is two or three legged, yet is has the largest implementation impact.

(I used the term “…should make any implementation impossible…”, this is security, never assume something is impossible!)

Redirects are your friend

The isolation between parties and the elegance of the standard is all around the re-directs:

  • each leg of the journey manages a specific functional part
  • for instance, if you call out to an OIDC provider for authentication, it can add in multi-factor authentication without a change in your software
  • as one part completes, it hands control over to the next part
  • finally control is returned to the browser, normally to the place the user started at prior to asking to login.

Tokens

This term is used nice and consistently, although the “claims” inside of the tokens can get a bit tangled up. Types of token are:

  • Access Token — the token to indicate successful authorisation (implied authentication)
  • Refresh Token — when an access token has expired you can use a refresh token to issue an new access token saving the user having to go through re-authorisation (re-authentication)
  • ID Token — validated identity associated with the other tokens

Remember that whilst an OAuth Token can be a JWT it often isn’t.

Endpoints

If you delve further into the standard, there are a range of combinations and permutations. The key ones are “authorize” and “token”.

According to the standard, these can have any name, but everyone generally uses those specific resource names.

Parameters

The parameters (either in the URL, body or claims inside JWTs) are consistent across the standards. There is a great IANA page that lists all the parameters and where they are defined:

This can also help you understand the interplay between the standards.

Anatomy of OAuth

OAuth is made up of many RFCs that build on each other, so their use of terms get overloaded / built upon — adding (each time this happens) nuances and capabilities that are not applicable in all settings. This makes it hard to follow, and can result in incorrect implementations.

A good example is the “JWT”. The standards make sure (quite rightly) that JWTs are used in the same way, fully interchangeable… but it can lead to confusion. You can end up with a solution that has JWTs used for: access token; id token AND for “client authentication”.

On top of that, a practical solution ultimately involves more than one security segment… Meaning you can end up having two overlapping OAuth mechanisms in your solution. For example, OAuth allows on “Authorisation Server” to also act as a “Relying Party” for the next segment.

So the following definitions are rough, to help you get a handle on this.

Authorisation Server

This is the server (or just a service as part of your application) that manages the OAuth issuing of tokens and their associated authorisation decisions. To do this, it needs to store and manage the lifetime of those tokens.

Client

This never refers to a person (which is “end-user” in OAuth terms or “resource owner”), it always refers to the calling software that wants authorisations to access some resources. In 95% of the cases this refers to your web server, not the “client browser”. When OIDC comes into the mix, the “client” is often synonymous with “relying party”

Resource Server

The services being protected by the access tokens issued. On smaller solutions the web application server can be both the resource, authorisation and identity server. API Gateways protected with an in-built OAuth act as both.

Scopes

Scopes… could be your friend, or they can just make life overly complicated. Their use in OAuth are optional, and should be tailored to your use cases. Think of them as transmitting detailed authorisation between parties. If you only have very simple yes/no type authorisations you might simply not need them.

There are different ways to use scopes, in order of importance:

  • User consent of what this application can access behind the scenes
  • Requesting access to resources
  • As a command

Some of the complications for scopes come when:

  • Informing your clients what scopes are available
  • Scopes are magic strings — the concept comes with a range of pro’s and con’s
  • If you use them, make sure there is a logical schema
  • Context — when are you requesting a scope? What scopes have been granted?
  • What happens if there are multiple OAuth segments? Do you transmit scopes between segments? If you do, you could start to introduce tight coupling between systems

Anatomy of OIDC

Finally, onto OpenID Connect, which is a much needed extension adding an identity layer to OAuth. However, it also adds a number of features that would have been great to have in OAuth type solutions. (In fact, the OpenID discovery endpoints triggered the creation of a draft RFC for OAuth discovery)

The terms used in OIDC, can get re-used when OAuth solutions are in play. This can create confusion, so in any documentation be consistent in their use.

Configuration discovery

OIDC allows for the publication of all the paths for the OIDC endpoints and options that the OIDC provider offers. These claims are published in JSON format with the path suffix of:

  • /.well-known/openid-configuration

If you use an OIDC library, you only need one URL to configure the client. Supply the authority path, and on first use the library picks up the OIDC details from the configuration endpoint.

Relying Party (RPs)

The clients of the OIDC Provider (OP), are referred to as “Relying Party” — and is generally a web server application

UserInfo endpoint

Depending on the solution, it might not be feasible to put all the meta-data about an identity into the ID Token. Where this is the case, the “userinfo” endpoint would be used to publish extra information about the authenticated identity.

This is not a search endpoint, it is always specific to the authenticating user — and (unsurprisingly) this endpoint is protected by the access token issued by the OIDC Provider.

--

--

Aubyn Crawford
0 Followers

I have worked as an independent IT Consultant for 26 years. I excel at bringing together and architecting complex solutions, and delivering them.