Vaultx.Auth.JWT (Vaultx v0.7.0)

JWT/OIDC authentication method for HashiCorp Vault.

This module implements comprehensive JWT (JSON Web Token) and OIDC (OpenID Connect) authentication for Vault, supporting both direct JWT authentication and full OIDC flows with extensive validation and security features.

Features

JWT Authentication: Direct JWT token validation and authentication
OIDC Support: Full OpenID Connect authentication flow
Multiple Providers: Support for various OIDC providers (Auth0, Google, Azure, etc.)
Flexible Validation: Configurable JWT validation with custom claims
Security: Built-in signature verification and claim validation
Enterprise Ready: Supports all Vault enterprise features

Authentication Types

JWT Authentication

Direct authentication using pre-signed JWT tokens:

{:ok, auth_response} = Vaultx.Auth.JWT.authenticate(%{
  role: "my-jwt-role",
  jwt: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
})

OIDC Authentication

Full OIDC authentication flow (requires browser interaction):

# Step 1: Get authorization URL
{:ok, auth_url} = Vaultx.Auth.JWT.get_oidc_auth_url(%{
  role: "my-oidc-role",
  redirect_uri: "https://myapp.com/callback"
})

# Step 2: User authenticates via browser and returns with code
# Step 3: Complete authentication with authorization code
{:ok, auth_response} = Vaultx.Auth.JWT.oidc_callback(%{
  state: "state_from_auth_url",
  code: "authorization_code_from_provider",
  nonce: "nonce_from_auth_url"
})

API Compliance

Fully implements HashiCorp Vault JWT/OIDC authentication:

Advanced Features

Custom Claims Validation

{:ok, auth_response} = Vaultx.Auth.JWT.authenticate(%{
  role: "my-role",
  jwt: "eyJ...",
  bound_claims: %{
    "department" => "engineering",
    "clearance_level" => "secret"
  }
})

Provider-Specific Configuration

# Azure AD integration
{:ok, auth_response} = Vaultx.Auth.JWT.authenticate(%{
  role: "azure-role",
  jwt: "eyJ...",
  provider_config: %{
    provider: "azure",
    tenant_id: "your-tenant-id"
  }
})

Vault Configuration

Before using this authentication method, configure it in Vault:

# Enable JWT auth method
vault auth enable jwt

# Configure OIDC provider
vault write auth/jwt/config \
  oidc_discovery_url="https://myco.auth0.com/" \
  oidc_client_id="your-client-id" \
  oidc_client_secret="your-client-secret"

# Create JWT role
vault write auth/jwt/role/my-jwt-role \
  role_type="jwt" \
  bound_audiences="https://myco.test" \
  user_claim="sub" \
  policies="default,myapp"

# Create OIDC role
vault write auth/jwt/role/my-oidc-role \
  role_type="oidc" \
  bound_audiences="your-client-id" \
  allowed_redirect_uris="https://myapp.com/callback" \
  user_claim="email" \
  policies="default,myapp"

Security Considerations

Validate JWT signatures using proper public keys or JWKS endpoints
Use appropriate bound claims to restrict access
Implement proper redirect URI validation for OIDC flows
Monitor authentication events in Vault audit logs
Use short-lived tokens when possible
Implement proper token refresh mechanisms

Summary

Functions

get_oidc_auth_url(params, opts \\ [])

Get OIDC authorization URL for browser-based authentication flow.

oidc_callback(params, opts \\ [])

Complete OIDC authentication flow using authorization callback parameters.

validate_jwt_local(jwt, opts \\ [])

Validate JWT token locally using JOSE library (optional).

Functions

get_oidc_auth_url(params, opts \\ [])

Get OIDC authorization URL for browser-based authentication flow.

Parameters

params - Map containing:
- :role - Name of the OIDC role
- :redirect_uri - Callback URL for OIDC flow
- :client_nonce - Optional client nonce for additional security

Returns

{:ok, %{auth_url: url, state: state, nonce: nonce}} - Authorization URL and flow parameters
{:error, %Vaultx.Base.Error{}} - Request failed with detailed error

Examples

{:ok, %{auth_url: url}} = Vaultx.Auth.JWT.get_oidc_auth_url(%{
  role: "my-oidc-role",
  redirect_uri: "https://myapp.com/callback"
})

# Redirect user to auth_url for authentication

oidc_callback(params, opts \\ [])

Complete OIDC authentication flow using authorization callback parameters.

Parameters

params - Map containing:
- :state - State parameter from authorization URL
- :code - Authorization code from OIDC provider
- :nonce - Nonce parameter from authorization URL
- :client_nonce - Optional client nonce if used in auth URL request

Returns

{:ok, auth_response} - Authentication successful with token information
{:error, %Vaultx.Base.Error{}} - Authentication failed with detailed error

Examples

{:ok, auth_response} = Vaultx.Auth.JWT.oidc_callback(%{
  state: "state_from_redirect",
  code: "auth_code_from_provider",
  nonce: "nonce_from_redirect"
})

validate_jwt_local(jwt, opts \\ [])

Validate JWT token locally using JOSE library (optional).

This function provides optional local JWT validation using the JOSE library. It can be used to validate JWT structure and claims before sending to Vault.

Parameters

jwt - JWT token string to validate
opts - Validation options:
- :verify_signature - Whether to verify JWT signature (default: false)
- :jwks_url - JWKS URL for signature verification
- :public_key - Public key for signature verification
- :expected_claims - Map of expected claims to validate

Returns

{:ok, %{header: header, payload: payload}} - JWT is valid with decoded parts
{:error, %Vaultx.Base.Error{}} - JWT validation failed

Examples

# Basic structure validation
{:ok, %{payload: payload}} = Vaultx.Auth.JWT.validate_jwt_local(jwt_token)

# With claim validation
{:ok, decoded} = Vaultx.Auth.JWT.validate_jwt_local(jwt_token,
  expected_claims: %{"iss" => "https://myco.auth0.com/"}
)

Note

This function requires the optional jose dependency. If not available, it will return {:error, :jose_not_available}.