Auth

# Use lightweight bearer-token hooks today and opt into OAuth contracts deliberately.

The default SDK package does not enable optional auth or pull OpenSSL. Server auth extension points are available through `cxxmcp::server`, while OAuth/JWT/DPoP surfaces stay behind explicit feature gates.

## Default Package Behavior

Auth is split between always-available server dispatch contracts and optional OAuth protocol scaffolding.

- `CXXMCP_ENABLE_AUTH=OFF` is the default.
- The default package does not export `cxxmcp::auth` or `cxxmcp::auth_openssl`.
- The default package does not call `find_package(OpenSSL)`.
- HTTP server auth hooks remain available through `cxxmcp::server`.

## Optional Auth Contracts

Enable auth only when consumers need the transport-neutral OAuth, metadata, lifecycle, token, registration, WWW-Authenticate, JWKS, JWT, and DPoP contract headers exposed by the `cxxmcp::auth` target. This option does not require OpenSSL by itself.

    cmake -S . -B build-auth -DCXXMCP_ENABLE_AUTH=ON
    cmake --build build-auth

    vcpkg install "cxxmcp-sdk[auth]" --overlay-ports=C:\path\to\cxxmcp\packaging\vcpkg\ports

## OpenSSL Crypto Option

Set `CXXMCP_AUTH_CRYPTO=OpenSSL` with `CXXMCP_ENABLE_AUTH=ON` when consumers need first-party crypto-backed helpers. This is the path that resolves OpenSSL and exports `cxxmcp::auth_openssl`.

- JOSE/JWK/JWS/JWT helpers cover compact JWS parsing, public JWK import, RS256/ES256 signature verification, and trusted JWKS JWT validation.
- `FetchingJwksJwtVerifier` adds transport-neutral JWKS fetch/cache integration for key rotation; applications still supply the HTTP fetcher.
- `OpenSslDpopSigner` and `OpenSslDpopVerifier` sign and verify ES256/RS256 DPoP proof JWTs.
- Server auth provider presets wire the OpenSSL JWT verifier, DPoP verifier, access-token hash helper, replay cache, and required-claim checks.

## Server-Side Auth Hook

Server authentication is implemented by application code through `mcp::server::AuthProvider`. The dispatcher authenticates the request before invoking typed tool, prompt, and resource handlers.

### AuthRequest

Carries transport-neutral request data such as headers and remote address.

### AuthIdentity

Stores the authenticated subject and claims for handler policy checks.

### AuthProvider

Application-owned interface for bearer-token validation, custom schemes, or OAuth verifier integration.

### HTTP Mapping

Auth-category failures map to HTTP 401 responses with a configurable `WWW-Authenticate` challenge.

## Server-Side OAuth Endpoints

When `CXXMCP_ENABLE_AUTH=ON`, `HttpTransport` can serve RFC 8414 authorization server metadata and wire application-provided callbacks to standard OAuth HTTP routes.

- `/.well-known/oauth-authorization-server` — RFC 8414 metadata discovery.
- `/authorize` — Authorization endpoint (GET). Redirects with authorization code.
- `/token` — Token endpoint (POST). Exchanges code for access token.
- `/register` — Dynamic client registration (POST, RFC 7591).
- `/revoke` — Token revocation (POST, RFC 7009).

The transport owns the HTTP routing; the application owns the authorization logic through `std::function` callbacks configured in `AuthorizationServerConfig`.

    mcp::auth::AuthorizationServerConfig as_config;
    as_config.issuer = "https://auth.example.com";
    as_config.authorization_handler = [](const auto& params) { /* ... */ };
    as_config.token_handler = [](const auto& params) { /* ... */ };

    mcp::server::HttpTransportOptions options;
    options.authorization_server = std::move(as_config);

## Client Bearer Token Helper

`mcp::client::HttpTransportOptions::auth_header` and `mcp::transport::StreamableHttpClientTransportOptions::auth_header` accept a token value, not a raw header. When set, the transport sends `Authorization: Bearer <token>` on outbound Streamable HTTP requests.

If the custom header map already contains `Authorization`, that explicit value wins. This keeps custom auth schemes and preformatted DPoP experiments possible without changing the bearer helper contract.

## HTTPS and Real Deployments

Streamable HTTP auth is intended for HTTPS in production. The SDK can run behind a TLS-terminating reverse proxy, and OpenSSL-backed auth helpers use the normal package manager dependency graph when explicitly enabled. OpenSSL must not be vendored into the repository.

## Explicit Non-Goals

The SDK still does not provide a built-in HTTP JWKS client, browser-opening or localhost loopback UX, or persistent credential storage. Those remain application responsibilities or future integration points.