OAuth2 Authentication

Nexus provides comprehensive OAuth2 support for securing your MCP endpoints. This is crucial for production deployments where you need to control access to your AI tools.

Configure OAuth2 authentication in your nexus.toml:

[server.oauth]
url = "https://your-auth-provider.com/.well-known/jwks.json"
poll_interval = "5m"
expected_issuer = "https://your-auth-provider.com"
expected_audience = "your-nexus-instance"

[server.oauth.protected_resource]
resource = "https://nexus.example.com"
authorization_servers = ["https://your-auth-provider.com"]

• url: The JWKS (JSON Web Key Set) endpoint URL for validating JWT tokens (required)
• poll_interval: How often to refresh the JWKS (optional, format: "5m", "1h", etc.)
• expected_issuer: The expected iss claim in JWT tokens (optional but recommended)
• expected_audience: The expected aud claim in JWT tokens (optional but recommended)

• protected_resource.resource: The URL of this Nexus instance as a protected resource (required)
• protected_resource.authorization_servers: List of trusted authorization server URLs (required)

The protected resource metadata is exposed at /.well-known/oauth-protected-resource as per RFC-9728.

When OAuth2 is enabled:

1. All endpoints require authentication (except /health and /.well-known/oauth-protected-resource)
2. JWT tokens are validated using the configured JWKS endpoint
3. Token claims are verified against expected issuer and audience
4. Access is granted or denied based on token validity

[server.oauth]
url = "https://your-tenant.auth0.com/.well-known/jwks.json"
poll_interval = "15m"
expected_issuer = "https://your-tenant.auth0.com/"
expected_audience = "https://nexus.your-domain.com"

[server.oauth.protected_resource]
resource = "https://nexus.your-domain.com"
authorization_servers = ["https://your-tenant.auth0.com/"]

[server.oauth]
url = "https://your-domain.okta.com/oauth2/default/v1/keys"
poll_interval = "10m"
expected_issuer = "https://your-domain.okta.com/oauth2/default"
expected_audience = "api://nexus"

[server.oauth.protected_resource]
resource = "https://nexus.your-domain.com"
authorization_servers = ["https://your-domain.okta.com/oauth2/default"]

One of Nexus's powerful features is the ability to forward OAuth2 tokens to downstream MCP servers. This enables seamless authentication across your entire AI infrastructure.

Use token forwarding when:

• Your downstream MCP servers use the same OAuth2 provider
• You want single sign-on (SSO) across all tools
• You need to maintain user context through the entire request chain

For each MCP server that should receive the forwarded token:

[mcp.servers.protected_api]
url = "https://api.example.com/mcp"

[mcp.servers.protected_api.auth]
type = "forward"

1. Client authenticates with Nexus using a JWT token
2. Nexus validates the token using configured OAuth2 settings
3. For servers with type = "forward", Nexus includes the same token in downstream requests
4. Downstream servers validate the token independently
5. These dynamic connections are cached per unique token (see MCP cache configuration for cache details)

When OAuth2 is enabled, clients must include a valid JWT token:

curl -X POST http://localhost:8000/llm/v1/chat/completions \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

• Verify the JWT token is valid and not expired
• Check that the JWKS URL is accessible
• Ensure expected claims match token contents
• Verify the Authorization: Bearer <token> header is present

Common issues when Nexus accepts a token but downstream servers reject it:

• Confirm type = "forward" is set for the server
• Ensure OAuth2 is enabled on the Nexus server
• Check server logs for authentication errors

• Audience (aud) mismatch: The token's audience claim might be set to Nexus's URL, not the downstream server's. Downstream servers often validate that they are the intended audience
• Resource identifier mismatch: If using RFC 8707, the downstream server might expect a specific resource claim
• Issuer (iss) mismatch: The downstream server might be configured to accept tokens from a different issuer
• Missing required scopes: The token might lack OAuth2 scopes required by the downstream server

• Wrong token type: Downstream server might expect an access token while receiving an ID token, or vice versa
• Token exchange required: Some enterprise setups require token exchange (RFC 8693) rather than direct forwarding
• Different JWT validation rules: The downstream server might have stricter validation (e.g., requiring additional claims)

• Clock skew: Time differences between servers can cause tokens to appear expired or not-yet-valid
• Different JWKS endpoints: Servers might use different key sets for validation
• Key rotation timing: Keys might have rotated between Nexus validation and downstream validation

• Ensure the JWKS URL is reachable from Nexus
• Check network connectivity and firewall rules
• Verify the poll_interval format is correct (e.g., "5m", "1h")

For enterprise deployments, consider that sophisticated authorization models may require token exchange (RFC 8693) rather than simple token forwarding:

• Token Exchange Flow: Instead of forwarding the same token, exchange it for resource-specific tokens
• Resource-Specific Tokens: Each downstream server receives a token with its URL as the audience
• Granular Scopes: Different downstream servers can require different OAuth2 scopes
• Audit Trail: Token exchange provides better visibility into which services are being accessed

Currently, Nexus supports direct token forwarding. For environments requiring token exchange, consider placing Nexus behind an API gateway that handles the exchange.

1. Always enable OAuth2 in production environments
2. Use HTTPS for all OAuth2 endpoints
3. Set expected claims (expected_issuer, expected_audience) to prevent token misuse
4. Monitor authentication failures in logs
5. Rotate signing keys periodically at your authorization server
6. Use short token expiration times with refresh tokens
7. Consider token exchange for enterprise environments with strict security requirements

• Configure Rate Limiting to protect against abuse
• Set up Client Identification for per-user features
• Enable CORS for browser-based clients