Decipher OAuth2 and OpenId Connect
In this article, we are going to understand various aspects that come into play, before we start using OAuth2 and OpenId Connect. Thanks to Keith Casey.
What OAuth and OpenID Connect are?
OAuth: Fundamentally, OAuth is an authorization framework. It gives you a consistent pattern to request, receive, and apply authorization policies across resources.
Before you understand OAuth you need to understand “Authentication” versus “Authorization”.
“Authentication is who you are while authorization is what you can do.”
Authorization depends on authentication but they’re not interchangeable.
My favorite analogy here is checking in to a hotel:
When you check in to a hotel, you present the front desk clerk with your driver's license or passport and a credit card. This establishes who you are, or your identity. That’s your authentication. Then they issue you a key card. Encoded on that card is what you have access to, which will include your room, but it might also include the gym or workout room. And if you have permission, it might also include the executive lounge. That’s your authorization. The best part is that your personal and billing information never leaves the front desk. This is OAuth.
In terms of OAuth terminology, you are the client.
The front desk is the authorization server that evaluates the authorization policies.
The key card is an access token, representing the result of those policies.
And your room, the executive lounge, etc., are the resources you want to protect.
Fundamentally, OAuth is an authorization framework. It gives you a consistent pattern to request, receive, and apply authorization policies across resources.
OpenID Connect: OIDC provides structure to a user profile, and allows you to selectively share it. To continue with our analogy from earlier, let’s say you want to eat at the hotel restaurant. With OIDC you can share your food allergies, and those alone, but not your e-mail address. Allowing you to share specific things is just authorization all over again. And that’s right, OpenID Connect is just a special case of OAuth. It’s designed specifically for single sign-on use cases and sharing profile information. That’s how we get SIAN with GitHub, Facebook, LinkedIn, and just about everything else.
• JWT — RFC 7519
• Token revocation — RFC 7009
• Token introspect — RFC 7662
• Dynamic Client Registration — RFC 7591/RFC 7592
• Authorization server metadata — RFC 8414
JWT — RFC 7519:
RFC 7519, which is the JSON Web Token, or JWT spec. We also call that a JWT token.
While OAuth doesn’t require using JWTs, it doesn’t even mention it in fact, we commonly use them because a JWT token is an easy way to encode and pass around JSON data without having to escape it for all the different contexts. But, please note, this is encoding, not encryption. Do not put sensitive information in a JWT. It’s not secure.
If you need to share sensitive data, an opaque token or even a JWE, also known as an encrypted JWT token, are much better options.
• iss — represent the ‘issuing auth server’
• iat — represent the ‘issued time’
• sub — represent the ‘who the token is about’ or subject
• aud — represent the ‘who should use it’ or audience
• exp — represent the ‘expiration claim’, the maximum time you can use this token
• various types of tokens (will discuss later)
Token revocation — RFC 7009:
Just like a hotel can revoke your key card for bad behavior, we can revoke a token for bad behavior. Is completely optional, but I don’t consider it optional. At some point, you or your team will make a mistake and accidentally leak a token. If you don’t have a way to revoke it, your doors are unlocked for minutes, hours, days.
Token introspect — RFC 7662:
This is usually used if we have an opaque token instead of a JWT and we still need to know what’s in it or what it represents. But the other purpose is that it determines if a token is still valid.
Token introspection becomes especially important if you’re using token revocation. When you use token revocation, only the authorization server knows the token has been revoked. After all, your expiration time in the token has not changed. With introspection, your client applications can query the authorization server to learn the same.
Dynamic Client Registration — RFC 7591/RFC 7592:
RFC 7591 allows for systems to register themselves with the authorization server for requesting tokens. It’s not one you’ll see in the wild very often, but it is useful when you have a self-service API portal where developers can register on their own. And once you create new OAuth clients, you need a way to edit and manage them.
RFC 7592 follows closely behind to find a consistent API for maintaining them.
Of course, since all these specifications are optional and will vary between OAuth providers, we need to know what capabilities we have available.
Authorization server metadata — RFC 8414:
Luckily, RFC 8414 is the authorization server metadata specification or more affectionately known as the OAuth discovery document. This allows us to query the authorization server itself, get back a JSON file with its capabilities and related endpoints, and then configure our applications. We don’t have to guess what’s available, the server will tell us.
OAuth 2.0 fundamentals
• authorization server
• access token
• access token
• refresh token
• grant type or flow
#four grant types
1. Authorization Code is used for back-end web apps
2. Implicit or Authorization Code with PKCE
3. client credential flow is used for microservices or service accounts
4. resource owner password flow
Now that we’ve drawn some boundaries around what OAuth is and isn’t, let’s get into the mechanics of how it actually operates.
Earlier, I used the analogy of a hotel key card. Let’s continue with that to describe the major components.
First, you’re the client,
the front desk is the authorization server,
the key card itself is the access token,
and your room is a resource.
But like any analogy, we left out a few parts to make it more easily understood. Let’s go ahead and add those concepts back now.
A scope is a permission, the client can request and be granted or denied. In our hotel example, the scopes available are your room, the pool, the executive lounge, and numerous other things.
Next, when you’re granted a set of scopes, you’re issued an access token. That access token is the hotel key card that gives you access now for a set period.
Next, we have the refresh token, and that gives you a new access token once the original expires.
In terms of the mechanics of OAuth, you take that refresh token back to the authorization server(front desk) and request a new access token. And it can grant or deny that based on your permissions.
The final aspect is how we request and receive that token in the first place. That’s called a grant type, or a flow.
There are four grant types defined in the base OAuth specification.
The core specification RFC6749 defines exactly two endpoints
• authorization endpoint
• token endpoint
Other common extensions of endpoints
• Introspect endpoint
• Revoke endpoint
• UserInfo endpoint
• Oauth discovery document endpoint
Authorization endpoint is used to interact with the user to confirm their identity. Therefore, it’s used for any user-facing grant types, such as the authorization code or the implicit flow. Once a user’s confirmed, or if there isn’t a user involved at all, that’s when we move to the token endpoint. This is where we actually get the tokens themselves.
Introspect endpoint, which allows you to analyze and decode a token.
Revoke endpoint, which allows you to invalidate and access a refreshed token.
UserInfo endpoint from the OpenID Connect specification, which publishes user profile data.
And one fun thing about all these endpoints, other than UserInfo specifically, they can all be made anything you want. Therefore, when you connect to a new OAuth provider, you need to figure out how it structures URLs, which is painful in the best of times. Luckily, to mitigate that struggle, there’s the well-known endpoint, or also known as the OAuth Authorization Server metadata document, or simply, the Oauth discovery document. The best part about this endpoint is that it’s fixed. You’re not allowed to create your own URL pattern. Next, within this document, it lists all the URL patterns for all the other endpoints, so life gets much easier.
to be continued….