Conquer Authentication with Ktor: Part 7 – Introducing OAuth 2.0

In our previous post, we wrapped up the discussion on Json Web Tokens. We’ve come far in this tutorial, gradually uncovering more complex and practical use cases. Now, we’re turning our attention to a widely adopted authorization protocol – Open Authorization 2.0. While JWT primarily ensures secure communication, OAuth focuses on the delegation of access. Today, we’ll have a closer look at key concepts of this authorization protocol.

Table of Contents

• OAuth vs OAuth 2.0 – Does It Matter?
• Contrasting OAuth with JWT
• How OAuth Works?
• Authorization Flow
  • Initiating Authorization
  • User Authentication and Granting of Permissions
  • Exchanging Authorization Code for Access Token
  • Accessing User Resources
• Terminology
• Summary

Since we will be using similar terminology, let’s differentiate OAuth 2.0 from what we’ve learned about JWT. First of all, let’s get clarity on what OAuth actually means.

OAuth vs OAuth 2.0 – Does It Matter?

The short answer is yes, it absolutely does. Both OAuth 1.x and 2.0 versions are driven by the very same ambition – to establish a safe standard for users to authenticate without revealing their credentials to third party systems and applications. However, OAuth 2.0 surpasses the original version by making the protocol easier to adopt in practice.

Here is what you should know if you’re considering an upgrade to OAuth 2.0 from the legacy version or wonder about the major differences between the two.

• Design overhaul. OAuth 2.0 is a complete rewrite of OAuth 1.0 from the ground up, sharing only overall goals and user experience.
• Mutually incompatible. OAuth 2.0 is not backwards compatible with OAuth 1.0 or 1.1.
• Implementation complexity. OAuth 2.0 is generally considered easier to implement due to its simplified use of signatures. This is a key differentiating factor.
• Security guarantees. Ease of implementation comes at a cost of security trade-offs. OAuth 2.0 revolves around bearer tokens which caters for an easy integration. On the other hand, these tokens can be stolen or compromised.
• Clear separation of concerns. OAuth 2.0 supports non-browser implementations and provides a clear separation of resource delivery and authorization.

If you want to know more details, I highly recommend reading What’s the difference? OAuth 1.0 vs OAuth 2.0 by the Synopsis editorial team.

For the sake of conciseness I’ll further refer to OAuth 2.0 as simply OAuth.

Contrasting OAuth with JWT

You’ve spent time and effort learning about JWT and now you’re, rightfully so, asking yourself whether it was worthwhile. Given, most integrations lean heavily on OAuth.

While OAuth is a protocol for authorization and JWT serves as a standard for generating tokens, they often work hand-in-hand. Authorizing your service with a third-party OAuth provider is typically quite simple, as you depend on them to issue arbitrary tokens. At this stage, you don’t even need to know that JWT exists. That’s the beauty of OAuth – it makes authorization easily accessible to virtually anyone. However, the equation changes when you switch roles and become an OAuth provider yourself. This is when you can leverage the capabilities of JWT, utilizing it to tackle the challenges of managing both access and refresh tokens efficiently.

Another benefit of JWT is that it stores all relevant information about the user. In other words, JWT makes authentication stateless which results in improved scalability.

How OAuth Works?

Imagine someone wants to use an online service. This service asks that person to create an account. The user can either register a separate account with this service or choose to log in using their existing Google or Facebook accounts, saving time and effort.

Assuming the user is already logged into their Facebook account, they click on “Log in with Facebook”. Next, they see a detailed list of the specific information Facebook will provide to the online service. This could include their first and last name, email, profile picture, etc., but it does not include sensitive information like the Facebook password.

If the user agrees to share this information, they confirm and voila! The user is now logged in to the online service without having to create a new account or share their Facebook password. They’ve used OAuth 2.0, which simplifies login and protects user credentials.

The reason why the online service can access user information through Facebook is because the service’s developers have registered it with Facebook. In doing so, they established a verified connection and received a unique identifier for the service. We’ll explore this process in more detail in the next section.

Authorization Flow

OAuth 2.0 is an authorization framework that enables third-party applications to access a user’s resources on another service or platform without sharing their credentials. The process involves various components, including the user (resource owner), the third-party application (client), the platform hosting the resources (resource server), and the authorization server.

OAuth 2.0 supports several authorization flows (grant types), but the most common one is the Authorization Code Grant flow. Here’s a step-by-step explanation of how it works:

Initiating Authorization

1. User initiates the authorization process. The user (resource owner) starts the process by clicking on a login button or a link on the third-party application (client) website or app. Please note that the client has no knowledge about the user.
2. Client redirects the user to the authorization server. The client redirects the user to the authorization endpoint residing on the authorization server. This is usually a webpage where the user can grant permission. The URL includes query parameters like the client ID, requested scopes (access level), and a redirect URI (where the user will be redirected after authorization is granted).

User Authentication and Granting of Permissions

3. Authorization server handles authentication. The authorizaton server asks the user for authentication credentials if not already logged in.
4. Authorization server asks for permission. Once the user is logged in, the authorization server presents the user with the requested permissions for the third-party application.
5. User grants permission. The user authorizes the requested permissions (scopes).

Exchanging Authorization Code for Access Token

6. Authorization server returns an authorization code: Once the user grants the requested permissions, the authorization server redirects the user back to the client’s specified redirect URL, including an authorization code as a query parameter.
7. Client requests an access token: The third-party application sends a request to the authorization server’s token endpoint with the received authorization code, client ID, client secret (if applicable), and redirect URL.
8. Authorization server issues the access token: The authorization server verifies the received information and sends a response containing an access token (and optionally a refresh token) for the third-party application to access the user’s resources.

Accessing User Resources

9. Client accesses the user’s resources: With the access token, the third-party application can now request the user’s resources from the resource server (API) within the authorized scopes. The access token is included in the Authorization header of each API request.
10. Resource server validates the access token: The resource server checks if the access token provided by the client is valid (usually by calling the authorization server or by validating a JWT access token locally).
11. Resource server returns the requested resources: If the access token is valid, the resource server returns the requested resources to the third-party application (client).

This flow provides a secure way to authorize third-party applications to access a user’s resources without sharing their credentials.

Terminology

In OAuth 2.0, there are typically four key roles, or parties involved.

1. Resource Owner. This is typically the end-user who owns the data or capabilities being accessed.
2. Client. This is the application requesting to access the resource owner’s account information or functionality.
3. Resource Server. This server hosts the protected user accounts, it’s essentially the API you’re seeking to access.
4. Authorization Server. This is what issues access tokens to clients on behalf of the resource owner, upon the owner’s approval.

Each role plays an integral part in a successful authorization flow. The Client is the app that wants to access the user’s account. As part of the process, the user (Resource Owner) must give the application (Client) permission to do this. This kick starts the authorization process. If all goes well, the application requests an access token (piece of data proving a permission was granted), which is issued by the Authorization Server. With the access token, the app can finally request information from the API (Resource Server).

Summary

OAuth 2.0 is an authorization framework that enables a third-party application to access a user’s resources on another platform without accessing the user’s credentials. The common authorization flow involves the user initiating the process, the application requesting access, and the authorization server granting an access token or a pair of access and refresh tokens.

Stay tuned for our next episode where we implement OAuth 2.0 with Ktor and Google.