More and more, APIs are the foundation of our experience. Whether we’re building customer-facing mobile apps, updating existing web apps, integrating with that cool, new device, or thinking about microservices, we can’t do that without APIs. Unfortunately, we rarely think about security and how we grant and revoke access. The consequences have already cost airlines, dating websites, and even governments hundreds of millions of dollars. You don’t want to be next.
Hi, in this article, we’ll talk about the most common and useful approach to securing access to our APIs, and those are OAuth 2.0 and OpenID Connect. So, stick around and find out what you know, and don’t know, about OAuth 2.0 or OpenID Connect. It’s going to be a lot of fun.
Let’s talk about what OAuth and OpenID Connect are.
Most people think they understand OAuth. Unfortunately, most people are wrong. OAuth is not a password sharing mechanism or protocol. It’s not even a log in process. The misunderstanding comes down to Authentication versus Authorization. These are affectionately known as AuthN and AuthZ respectfully.
Authentication is who you are .
Authorization is what you can do.
Authorization depends on authentication but they’re not interchangeable.
Example : 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 drivers license or passport and a credit card. This establishes who you are, or your identity. 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 which 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.
Now let’s talk about 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.
How it work ?
Now that we’ve talked about the overall concept of OAuth, let’s get specific about what it is at a practical everyday level. On the surface, OAuth looks complicated, but if you look just below the surface, you’ll realize it’s still complicated. That’s because OAuth 2.0 is a framework, or a loose operating agreement, at how we’re going to interact. Unlike a strict contract, it leaves many things undefined. While this is frustrating at first glance, it gives us flexibility to address new problems, technologies and use cases that the creators didn’t imagine. That is powerful. There are about a dozen extensions that are useful on a day-to-day basis with OAuth. I’ll cover OpenID Connect in the next section, but the ones that are relevant in general are :
- Token revocation
- Token introspect
- Dynamic Client Registration
- Authorization server metadata
JWT : The first one we’ll deal with is 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. Finally a JWT token includes fields like iss and iat, which represent the issuing auth server and the issued at time. Then includes fields like sub and aud, which establish who the token is about and who should use it, also known as the subject and the audience. Think of this as the to and the from on an email. And finally there’s the exp, or expiration claim, which tells you the maximum time you can use or trust this token.
Token revocation : Next, we have RFC 7009, or the token revocation spec. Just like a hotel can revoke your key card for bad behavior, we can revoke a token for bad behavior. Yes, this extension, like any other, 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. Until the expiration time is hit, who knows how many people could misuse that token. I recommend that you treat this extension as required, too.
Token introspect : Next we have RFC 7662, or the token introspection spec. 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 : Next, we have RFC 7591, which is the dynamic client registration specification. This 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 : Now, 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 end points, and then configure our applications. We don’t have to guess what’s available, the server will tell us. Once again, that is incredibly powerful.
OAuth and OpenID Connect
Now let’s talk OpenID Connect, or OIDC. At first glance, OIDC looks nothing like OAuth. Instead of a loose agreement, it has a rigid structure. Instead of arbitrary tokens, it specifically defines both the format and the content of those tokens. In fact, most people think OAuth and OIDC are competing specifications. If you look closer, you’ll realize that’s not the case at all. Instead of OIDC being in conflict with OAuth, you’ll see that it’s just another extension. But in fact, it’s one of the most widely implemented and used extension because it gives us tool for single sign-on and profile sharing. Of their numerous differences, there are three main ones that we care about in relation to this article are as the following .
- Access and refresh tokens
- Authorize and token endpoint
- Authorization Code ,Implicit,Resource Owner Password,and Client Credentials
- +ID Tokens
- +Userinfo endpoint
- Authorization Code ,Implicit
- First, OIDC adds another type of token, the ID token. Unlike OAuth tokens in general, this one must be a JWT, and within that has specific naming requirements and contents that must be there. In vast majority of cases, this is the user’s profile information.
- Next, it adds another endpoint, the user info endpoint. You use this to retrieve user info. It’s kind of tricky like that. Now, this will generally retrieve the same user information which was available in the ID token itself. Therefore, if our applications trust the system that issued the token, we know who signed in when and can use that to create a profile on our end. It simplifies creating a new user account by not forcing them to retype profile information.
- Finally, OpenID Connect only supports a subset of the OAuth grant types. but you’ll soon see how these are the only ones which are both user oriented and considered very secure.
Now, if you look at OIDC more closely, you should see that it’s not in competition with OAuth at all, but just a structured pattern on top of the existing framework. And most likely, you’re using OpenID connect right now. If you signed in to LinkedIn Learning with your LinkedIn account, you saw it. You clicked the log in button. Your browser opened a window for you to log in to LinkedIn. Then you did, the window closed, and you were redirected back. As a result, you now have a full profile based on your LinkedIn data. You never had to share your credentials or retype that information. How easy is that?
Before we end this article, I’d like to leave you with a few things to help your team and expand your skills further. First, I’d consider myself a failure if I didn’t mention these benefit resources :
- Aaron Parecki’s book, “OAuth 2.0 Simplified”
Hopefully it’ll convince you, your team, and your management, not to do it yourself, or if you absolutely have to, how to do it better. But seriously, don’t build it yourself. The consequences of getting this wrong are catastrophic. Finally, I encourage you to read the specifications relevant to your specific challenges. Oauth.com has a great map that I’ve linked to here. The reason I recommend reading the specifications is that people have crammed a lot of ideas and assumptions into their understanding of OAuth, and too often they’re wrong. What they’ve interpreted as hard requirements are often merely suggestions, or occasionally just a vendor’s particular take on the situation. You need to understand what is and is not part of what you’re doing, what you need, and what your tools actually support.
And the next time you hear somebody say, “Do you support OAuth?” You can cringe right along with me. Now go out there and build better, more secure, and standard spaced applications and API’s. Thanks for watching.