# How the Macro Authentication Service Handles JWT Tokens: Implementation Guide

> Learn how the Macro authentication service handles JWT tokens. Discover implementation details using the macro_auth crate, AWS Secrets Manager, and Axum middleware for secure request validation.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: implementation-guide
- Published: 2026-08-17

---

**The Macro authentication service leverages the `macro_auth` crate to decode and verify JWTs using `JwtValidationArgs` for configuration and `MacroAuthJwtValidator` for enforcement, loading signing secrets from AWS Secrets Manager and validating tokens on every request via Axum middleware.**

The `macro-inc/macro` repository implements a production-grade JWT authentication flow within its authentication service. By combining the `macro_auth` library with asynchronous secret management, the service dynamically loads validation parameters at startup and enforces cryptographic token verification across all API endpoints.

## JWT Validation Architecture Overview

The authentication flow centers on three core components defined in the `macro_auth` crate: the configuration struct `JwtValidationArgs`, the validator implementation `MacroAuthJwtValidator`, and the middleware handler that executes validation per request. In [`services/authentication_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs), the service initializes these components during startup, creating a centralized authorization state that Axum injects into request handlers.

The `JwtValidationArgs` struct (imported at line 36) manages validation parameters including the expected issuer, audience, and HS256 signing secret. This configuration object feeds into `MacroAuthJwtValidator`, which implements the `MacroAuthorizationState` trait used throughout the application to gate access to protected resources.

## Configuring JWT Validation with JwtValidationArgs

Before processing requests, the service constructs validation arguments that define acceptable token criteria and secure key material.

### Loading Secrets from AWS Secrets Manager

The `JwtValidationArgs` struct retrieves the JWT signing secret asynchronously during initialization. In production environments, it fetches the secret from AWS Secrets Manager, while local development uses a test secret. This initialization occurs at lines 176-179 of [`services/authentication_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs):

```rust
let jwt_args = JwtValidationArgs::new_with_secret_manager(
    config.environment,
    &secretsmanager_client,
).await?;

```

### Validation Parameters and Constraints

The `JwtValidationArgs` instance configures validation rules including the expected issuer (`iss`), audience (`aud`), and expiry checks. These constraints ensure tokens match the specific service configuration before cryptographic verification occurs. The validator rejects tokens with invalid signatures, expired timestamps, or mismatched claims according to these parameters.

## Implementing the Validator with MacroAuthJwtValidator

Once configured, the `JwtValidationArgs` feeds into `MacroAuthJwtValidator`, which serves as the concrete implementation of the authorization interface. Lines 199-202 of the main service file demonstrate this composition:

```rust
let auth_state = MacroAuthorizationState::new(Arc::new(AuthorizationService::new(
    MacroAuthJwtValidator::new(jwt_args.clone()),
    InternalAuthConfig { api_key: internal_api_key.to_string(), default_user_id: None },
    macro_authorization::NoBotAuthorizer,
)));

```

This architecture separates token validation logic from business logic, allowing the `MacroAuthJwtValidator` to focus exclusively on cryptographic verification while the `AuthorizationService` handles higher-level access control policies.

## Processing Requests with Middleware Validation

Incoming requests undergo validation through Axum middleware defined in [`services/mcp_auth_proxy/src/inbound/middleware.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_auth_proxy/src/inbound/middleware.rs). The middleware extracts the Bearer token from the `Authorization` header and invokes the validation handler provided by the `macro_auth` crate.

At line 89, the middleware calls the validation function:

```rust
let jwt_token = match handler(&jwt_args, &token) {
    // Token valid: proceed with request
    // Token invalid: return 401 Unauthorized
};

```

The `handler` function, defined in [`crates/macro_auth/src/middleware/decode_jwt.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_auth/src/middleware/decode_jwt.rs), performs the actual validation:
- Verifies the HS256 signature against the loaded secret
- Checks the `iss` claim against the configured issuer
- Validates expiration timestamps
- Extracts the user ID claim for downstream use

The middleware returns a typed `JwtToken` struct on success, which handlers use to identify the authenticated user.

## Summary

- The Macro authentication service uses the `macro_auth` crate for JWT operations, specifically the `JwtValidationArgs` and `MacroAuthJwtValidator` types.
- Secrets load asynchronously from AWS Secrets Manager at startup via `JwtValidationArgs::new_with_secret_manager()` as implemented in [`services/authentication_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs).
- Validation occurs in Axum middleware at [`services/mcp_auth_proxy/src/inbound/middleware.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_auth_proxy/src/inbound/middleware.rs), line 89, using the `handler` function from [`crates/macro_auth/src/middleware/decode_jwt.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_auth/src/middleware/decode_jwt.rs).
- The system supports HS256 signature verification with configurable issuer and audience constraints.

## Frequently Asked Questions

### Where does the Macro authentication service store JWT signing secrets?

The service retrieves JWT signing secrets from AWS Secrets Manager in production environments, or uses local test secrets during development. This occurs during startup in [`services/authentication_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs) when calling `JwtValidationArgs::new_with_secret_manager()`, which accepts the environment configuration and secrets manager client as parameters.

### What validation algorithm does the Macro authentication service use for JWTs?

The implementation uses HS256 (HMAC with SHA-256) for signature verification. The `handler` function in [`crates/macro_auth/src/middleware/decode_jwt.rs`](https://github.com/macro-inc/macro/blob/main/crates/macro_auth/src/middleware/decode_jwt.rs) validates the token signature against the secret loaded into `JwtValidationArgs`, ensuring only tokens signed with the correct key are accepted.

### How does the authentication service inject JWT validation into API requests?

The service uses Axum's state injection pattern. It creates a `MacroAuthorizationState` containing the `MacroAuthJwtValidator` in [`services/authentication_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs), then applies middleware at [`services/mcp_auth_proxy/src/inbound/middleware.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_auth_proxy/src/inbound/middleware.rs) that extracts the Bearer token from the `Authorization` header and calls the validation handler for every protected request.

### Can the JWT validation parameters be configured for different environments?

Yes. The `JwtValidationArgs` struct accepts an environment parameter that determines whether to load secrets from AWS Secrets Manager or use local test credentials. This allows the same codebase to operate in development, staging, and production with different validation configurations without code changes.