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

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.

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.