I was recently tasked with adding single sign-on functionality to a client application. Along with their existing credentials-based authentication flow, they wanted to allow users of third-party systems to access the application without creating a separate set of credentials.
This was a new task for me — I’d never had to delve into implementing this sort of authentication in the past. Authentication like this had always seemed like a black box until then. From a user’s perspective, you click a button, you see some redirects happen and the next thing you know, you’re logged in. But what were these redirects? What were these codes and tokens being exchanged between the two endpoints? How does one begin to understand and build such a system?
In this post, we will explore the basics of OpenID Connect (OIDC) authentication workflows and hopefully demystify some of the jargon that is the OAuth 2.0 standard.
Picture This
Let’s say there’s this hip, new restaurant in town that everyone wants to go to. However, this restaurant is exclusive and they need to know who’s coming and whether they have a reservation.
You, as a customer, would like to dine at this restaurant. You don’t have a reservation yet, so you’ll need to get one. The restaurant doesn’t know you, so you use a trusted middleman: OIDC. You ask OIDC, “Could you assist me in getting a reservation at this new restaurant?”
OIDC then tells you, “Sure, I can do that, but I’ll need to validate your identity first.” You then share your credentials with OIDC.
After OIDC validates your identity, they affirm that you’re eligible for a reservation and send an Authorization Code back to you.
You take this Authorization Code and give it back to the restaurant. After receiving the authorization code, the restaurant provides you with a reservation token — your pass to dine in the restaurant. With this token, you can now access resources from the restaurant, such as the menu, ordering food, etc.
Just keep in mind that your reservation is typically time-limited, so you’ll need to dine within a certain time frame before it expires. If it expires, you’ll need to get a new one.
Mapping The Terminology
Based on the above analogy, here is how I’d map terms to their OAuth equivalent:
- What is OAuth? – Think of OAuth as the restaurant’s protocol or set of rules to ensure each customer has a valid reservation
and has the right to access the restaurant. - What is OIDC? – This (OpenID Connect) is like the maître d’ who checks your ID at the door to confirm that you are indeed the person
who made the reservation. It’s an extra layer of security on top of OAuth that also verifies who you are. - What is an authorization code? – This is a one-time ticket or code you get from the maître d’ (OIDC) after confirming your identity. You give it to the hostess (the application), proving your claim that you have a proper reservation (like a voucher).
- What is a client ID? – In this analogy, the Client ID would be akin to your name for the reservation. It’s what identifies you as the
customer when you’re trying to get a reservation. - What is a client secret? – This would be like a secret restaurant-goer’s password that you use to prove you’re a bona fide diner.
It’s a secret known only to you and the restaurant and mustn’t fall into the wrong hands. It’s used, along with your client ID, to get that initial authorization code. - What is an identity provider (IdP)? – This would be the Maître d’ (OIDC), the one checking IDs and confirming that they are secure and legitimate. They provide the identity-proofing and ensure the right person is accessing the service. In a broader context, this could be a service used to manage and verify identity, like Facebook or Google, which many sites allow you to use to log in.
- What is an access token? – This is like the badge or wristband you get after you give the hostess your authorization code, which
allows you to order food, drink, and otherwise take full advantage of the restaurant’s services. It allows you to interact with and access certain parts of the restaurant. - What is a refresh token? – Imagine if your Access Token (badge/wristband) had a time limit and expired. The refresh token would be like a coupon that lets you get a new badge/wristband without going through the whole reservation process all over again. It’s used to get a new access token when the old one expires.
OIDC Visualized
If you’re a visual learner like me, the following sequence diagrams may help. They attempt to make better sense of the exchange of credentials for codes and codes for tokens, and its relation to our restaurant reservation analogy.
OIDC and OAuth 2.0 Demystified
The technical jargon in these standards often seems difficult and filled with complicated mechanics. But, they can be understood by stepping outside the technical mindset and diving into illustrative analogies. Rest assured, it’s forgivable if you didn’t grasp everything in one go. I surely did not. I hope this post helps you picture the various parts of the standard in a more familiar and relatable way.