Understanding and Implementing OAuth 2.0 in Rust with oxide-auth

Overview of the OAuth 2.0 Protocol

OAuth 2.0 is a widely adopted authorization framework that enables applications to obtain limited access to user accounts on an HTTP service, such as Facebook, GitHub, or Google. It works by delegating user authentication to the service that hosts the user account and authorizing third-party applications to access the user’s account. OAuth 2.0 provides a more streamlined and secure workflow for both developers and users compared to earlier methods like client-side user credentials.

Key Concepts of OAuth 2.0

1. Roles:

• Resource Owner: The user who authorizes an application to access their account.
• Client: The application requesting access to the user’s account.
• Resource Server: The server hosting the user data.
• Authorization Server: The server that authenticates the resource owner and issues access tokens to the client after approval.

2. Tokens:

• Access Token: A token that the client uses to access the resource server on behalf of the user.
• Refresh Token (optional): A token used to obtain a new access token when the original expires without requiring the user to repeat the authentication process.

3. Grant Types: The method through which a client acquires an access token. The most common types are:

• Authorization Code: Used with server-side applications, where the client can securely store the client secret.
• Implicit: Designed for clients implemented in a browser using a scripting language, such as JavaScript.
• Resource Owner Password Credentials: Used when there is a high level of trust between the resource owner and the client.
• Client Credentials: Used for application access without the need for user interaction.

4. Redirect URIs: URLs where the client will be redirected after authorization has been granted by the user.

Workflow of OAuth 2.0

The typical flow involves several steps:

1. Authorization Request: The client requests authorization from the user.
2. User Approval: The user approves the request, often via a user interface provided by the authorization server.
3. Client Receives Authorization Code: In the case of the Authorization Code grant type, the client receives an authorization code.
4. Token Exchange: The client exchanges the authorization code for an access token.
5. Access Resource: The client uses the access token to access the resource server on behalf of the user.

The oxide-auth crate

The oxide-auth crate in Rust is designed to facilitate the integration of OAuth 2.0 authorization into web applications. This crate abstracts much of the complexity associated with the OAuth 2.0 protocol, providing developers with a more straightforward path to implementing authentication and authorization in their applications. Below, we'll explore some of the key components of the oxide-auth crate, their purposes, and provide a basic code example to illustrate their usage.

Key Components of oxide-auth

1. Registrar: The Registrar component is responsible for managing client information. It verifies client credentials and the redirection URI presented during the authorization request.
2. Authorizer: This component handles the generation and storage of authorization codes. It’s involved in the first phase of the Authorization Code flow, where the client is authenticated and the user’s consent is obtained.
3. Issuer: The Issuer is responsible for generating tokens (access and refresh tokens) after successful authentication and authorization. It processes the authorization code and client credentials to issue these tokens.
4. Solicitor: The Solicitor component is used to interact with resource owners (users) for their consent in the authorization process. It’s essential in scenarios where user interaction is required.
5. Endpoint: oxide-auth provides an endpoint interface that integrates the other components to handle OAuth 2.0 requests following the standard flows.

Implementation Example

This example will focus on setting up an Authorization Code flow. Remember, this example is for educational purposes and should be further developed for production use.

Step 1: Set Up Rust Project and Dependencies

Create a new Rust project and update Cargo.toml with necessary dependencies:

cargo new rust_oauth_server
cd rust_oauth_server

In Cargo.toml, add:

[dependencies]
actix-web = "4"
oxide-auth = { version = "0.5", features = ["actix"] }
serde = "1.0"
serde_json = "1.0"

Step 2: Basic Server Setup

In src/main.rs, set up the basic server:

use actix_web::{web, App, HttpServer, HttpResponse};

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .route("/authorize", web::get().to(authorize))
            .route("/token", web::post().to(token))
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}
async fn authorize() -> HttpResponse {
    HttpResponse::Ok().body("Authorization endpoint")
}
async fn token() -> HttpResponse {
    HttpResponse::Ok().body("Token endpoint")
}

👏 Your Support Matters: If you enjoy the content, please give it claps on Medium and share the content away! Your support encourages me to continue creating and sharing Rust resources.

Step 3: Implementing OAuth Logic

Client Registry

Implement a simple client registry:

use oxide_auth::primitives::registrar::{Client, ClientMap};

fn client_registry() -> ClientMap {
    let mut clients = ClientMap::new();
    clients.register_client(Client::public(
        "public-client",
        "http://localhost:8080/callback",
        "default-scope".parse().unwrap(),
    ));
    clients
}

Authorization and Token Endpoints

Implement the authorization and token endpoints:

use oxide_auth::frontends::simple::endpoint::{Endpoint, OAuthError, OwnerConsent, OwnerSolicitor, QueryParameter, WebRequest, WebResponse};
use oxide_auth::frontends::simple::endpoint::{FnSolicitor, Generic};
use oxide_auth::frontends::actix::{OAuthRequest, OAuthResponse, OAuthFailure};
use oxide_auth::primitives::prelude::*;

async fn authorize(mut req: OAuthRequest<WebRequest>) -> Result<OAuthResponse<WebResponse>, OAuthFailure> {
    let client_registry = client_registry();
    let authorizer = AuthMap::new(RandomGenerator::new(16));
    let solicitor = FnSolicitor(|_req| Ok(())); // Simplified user consent
    let mut oauth = Endpoint::new(client_registry, authorizer, solicitor);
    match oauth.authorize(req.into_inner()).await {
        Ok(response) => Ok(response.into()),
        Err(err) => Err(err.into())
    }
}
async fn token(mut req: OAuthRequest<WebRequest>) -> Result<OAuthResponse<WebResponse>, OAuthFailure> {
    let client_registry = client_registry();
    let authorizer = AuthMap::new(RandomGenerator::new(16));
    let issuer = TokenMap::new(RandomGenerator::new(16));
    let mut oauth = Endpoint::new(client_registry, authorizer, issuer);
    match oauth.token(req.into_inner()).await {
        Ok(response) => Ok(response.into()),
        Err(err) => Err(err.into())
    }
}

Step 4: Running the Server

Run the server:

cargo run

This example sets up the basic structure for an OAuth 2.0 server using oxide-auth with the Authorization Code flow. The /authorize endpoint is for authorization, and the /token endpoint is for token exchange. The user consent part is overly simplified for this example. For a real-world application, you'd need to implement proper user authentication and consent mechanisms.

Creating a simple client to test the OAuth server

For this example, I’ll provide a basic Rust client using reqwest and serde to communicate with the OAuth server. This client will simulate the steps a typical OAuth client would take to obtain an access token using the Authorization Code flow.

Step 1: Set Up Rust Project and Dependencies

Create a new Rust project for the client:

cargo new rust_oauth_client
cd rust_oauth_client

In Cargo.toml, add the necessary dependencies:

[dependencies]
reqwest = "0.11"
serde = "1.0"
serde_json = "1.0"
tokio = { version = "1", features = ["full"] }

Step 2: Implementing the Client

In src/main.rs, implement the client logic:

use reqwest::{Client as HttpClient, Response};
use serde::{Deserialize, Serialize};
use std::error::Error;

#[derive(Deserialize)]
struct AuthResponse {
    // Adjust these fields according to the response format from your OAuth server
    code: String,
}
#[derive(Serialize)]
struct TokenRequest {
    client_id: String,
    grant_type: String,
    code: String,
    redirect_uri: String,
}
#[derive(Deserialize)]
struct TokenResponse {
    // Adjust these fields according to the response format from your OAuth server
    access_token: String,
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let client = HttpClient::new();
    // Step 1: Get Authorization Code
    // In a real-world scenario, this would involve redirecting the user to the authorization URL
    // and then capturing the code from the callback. For simplicity, we simulate it here.
    let auth_response: AuthResponse = client
        .get("http://localhost:8080/authorize?response_type=code&client_id=public-client&redirect_uri=http://localhost:8080/callback&scope=default-scope")
        .send()
        .await?
        .json()
        .await?;
    // Step 2: Exchange Authorization Code for Access Token
    let token_request = TokenRequest {
        client_id: "public-client".to_string(),
        grant_type: "authorization_code".to_string(),
        code: auth_response.code,
        redirect_uri: "http://localhost:8080/callback".to_string(),
    };
    let token_response: TokenResponse = client
        .post("http://localhost:8080/token")
        .json(&token_request)
        .send()
        .await?
        .json()
        .await?;
    println!("Access Token: {}", token_response.access_token);
    Ok(())
}

Step 3: Running the Client

Run the client with:

cargo run

This client performs two main steps:

1. Get the Authorization Code: It sends a GET request to the /authorize endpoint of the OAuth server. Note that in a real-world scenario, this step would involve user interaction, where the user would log in and consent to the authorization request.
2. Exchange the Authorization Code for an Access Token: It sends a POST request to the /token endpoint with the necessary data (including the received authorization code) to obtain an access token.

This example provides a basic framework for a Rust client interacting with an OAuth server. Remember, this is a simplified client meant for testing and demonstration purposes. In a real-world application, the client would need to handle user redirections, consent, and securely store tokens. Additionally, error handling and security considerations are crucial for a robust implementation.

🚀 Explore More Rust Resources by Luis Soares