Dec 28, 2020
Open ID Connect, OAuth and What Does It Mean?
The principles behind SAML, OAuth, Open ID Connect (OIDC) are all straight forward.
The specifications are very well specified ;-). There are some great starter projects, NuGet packages and samples available… But as with all things “authentication” they are poorly contextualised. It is easy to put a whole bunch of stuff into a solution you don’t need.
Whenever I delve into some “auth” work, the key points that are never clear are:
- Is the code for “publishing an identity server” or “client” style solution?
- The examples are always tangled up with other products that are not relevant
- Given any auth solution has to have multiple servers, the code I have downloaded to use — which server does it apply to?
- I just want to secure my API, I don’t even need a login page, why is it so complicated?
- And my all time favourite — why shorten things to “auth” when the killer distinction is between “authentication” and “authorisation”? The Wikipedia definition of OAuth only clearly states that OAuth standard is about authorisation in the third paragraph…
So, I am putting together a few pages to try and help demystify some of this, and help others get into OAuth and OIDC solutions with understanding. If you have suggestions / ideas on how to improve the pages please comment.
These pages are not to give a full explanation of OAuth and OIDC, nor provide flow diagrams (shock horror)… It is more aimed at someone who has heard of OAuth and OIDC and now wants to use it in anger. So, I am trying to present this subject from a different angle that will hopefully make it easier to implement these standards in the real world.
The examples pages are quite detailed, but I hope I have brought out the “why” in the code and commands to help utilise the right bits of the standards and technology. It also means there will be some very obvious statements for many readers… sorry!
Golden rule for OAuth
Don’t cross the streams (or flows in this case) — focus on the one you want to use. Think about:
- Context — are you: Pre or post Access token?
- Context — are you: at the client, your web server, authorisation server or authentication server
- OAuth is like electricity — it is everywhere in your design, plug a US device into a UK power supply and it blows up. The parts of OAuth look the same but you must connect them correctly
Here be dragons… misnome of simplicity
A good developer is fully capable of using OAuth and OIDC, and reading all the RFCs (some of which include great best practice guidance). A number of the RFCs repeat phrases such as : “this specification focuses on client developer simplicity and requires only an HTTP client and JSON parser, which are nearly universally available in modern development environments” (from RFC 8693 section 1)
Repeating the same thing, over and over, doesn’t make it true! Every element of the standard has proviso’s and MUST / SHOULD statements about checks that SHOULD take place before trusting a request or response. This means that you can’t just parse some JSON and use the data — you have to validate it, apply context, etc.
Part of the drive for these pages is to show some standard (mostly Microsoft biased) libraries that wrapper this complexity and provide secure implementations. This, in turn, should deliver the power and safety you expect from OAuth and OIDC.
What can I use OAuth & OIDC for?
Far too many things actually, but I’ve focused on three high level scenarios:
- Create a single page app that is authenticated by Facebook / google. Etc.
- Build a full web app that also uses Facebook APIs
- No people involved — securing connections between systems
Other use case examples:
- Build a full web app with client and server aspects
- Create a single page app that uses multiple APIs, but with the same identity
- Build a full web app that uses multiple APIs, but with the same identity
- Embed an application in a hardware device that needs to be easily linked to a person
- Build an API Gateway for your in-house applications
- Build an API Gateway to bring together diverse APIs into one place, with multiple identities
OAuth provides you the framework to do any of the above and many more variants — but it is a framework, you must plan carefully to wire it all up.
OAuth is in TWO Parts
Sounds obvious… when you are dabbling with APIs, you often “just want to call an API”… You can’t do that with OAuth. It boils down to:
- Getting an Access Token (authorisation)
- Calling an API many times with the same Access Token
Getting an Access Token
This is the really complex part, and there are so many options on how to design your authorisation and retrieve the token. Your choices at this point are focus around:
- Selecting the most secure way, for your chosen application architecture, to obtain an access token
- Enabling a hook into your preferred authentication solution
- Authorisation checks — fixing the privileges attached to this access token
Using your Access Token
Now that you’ve been granted access, time to make use of it. Attach the access token to every API call (usually in the Authorization header as a Bearer token).
Generally there are no complex authorisation rules applied now — you have your Access Token. You can get rejected when you try and access something that hasn’t been granted by your access token, but the complex calculations were done and the results stored.
Main Links & Further Reading
Orientation of terms
I’ve created page to help you orientate yourself with the basic terms: OAuth — orientation and terms
Worked example pages
A few to start with:
- Example: Single Page App using Microsoft OIDC
- Example: Web Client & Server App Authenticating with NHS Digital Identity via OAuth
- Example: Web Server App Authenticating with NHS Digital OAuth
The key references are the standards themselves:
