diff --git a/docs/clients/auth/bearer.mdx b/docs/clients/auth/bearer.mdx new file mode 100644 index 000000000..68459ebf6 --- /dev/null +++ b/docs/clients/auth/bearer.mdx @@ -0,0 +1,81 @@ +--- +title: Bearer Token Authentication +sidebarTitle: Bearer Auth +description: Authenticate your FastMCP client using pre-existing OAuth 2.0 Bearer tokens. +icon: key +--- + +import { VersionBadge } from "/snippets/version-badge.mdx" + + + + +Bearer Token authentication is only relevant for HTTP-based transports. + + +You can configure your FastMCP client to use **bearer authentication** by supplying a valid access token. This is most appropriate for service accounts, long-lived API keys, CI/CD, applications where authentication is managed separately, or other non-interactive authentication methods. + +A Bearer token is a JSON Web Token (JWT) that is used to authenticate a request. It is most commonly used in the `Authorization` header of an HTTP request, using the `Bearer` scheme: + +```http +Authorization: Bearer +``` + + +## Client Usage + +The most straightforward way to use a pre-existing Bearer token is to provide it as a string to the `auth` parameter of the `fastmcp.Client` or transport instance. FastMCP will automatically format it correctly for the `Authorization` header and bearer scheme. + + +If you're using a string token, do not include the `Bearer` prefix. FastMCP will add it for you. + + +```python {4} +from fastmcp import Client + +async with Client( + "https://fastmcp.cloud/mcp", auth="" +) as client: + await client.ping() +``` + +You can also supply a Bearer token to a transport instance, such as `StreamableHttpTransport` or `SSETransport`: + +```python {5} +from fastmcp import Client +from fastmcp.client.transports import StreamableHttpTransport + +transport = StreamableHttpTransport( + "http://fastmcp.cloud/mcp", auth="" +) + +async with Client(transport) as client: + await client.ping() +``` + +## `BearerAuth` Helper + +If you prefer to be more explicit and not rely on FastMCP to transform your string token, you can use the `BearerAuth` class yourself, which implements the `httpx.Auth` interface. + +```python {5} +from fastmcp import Client +from fastmcp.client.auth import BearerAuth + +async with Client( + "https://fastmcp.cloud/mcp", auth=BearerAuth(token="") +) as client: + await client.ping() +``` + +## Custom Headers + +If the MCP server expects a custom header or token scheme, you can manually set the client's `headers` instead of using the `auth` parameter: + +```python {4} +from fastmcp import Client + +async with Client( + "https://fastmcp.cloud/mcp", headers={"X-API-Key": ""} +) as client: + await client.ping() +``` diff --git a/docs/clients/auth/oauth.mdx b/docs/clients/auth/oauth.mdx new file mode 100644 index 000000000..e1973edce --- /dev/null +++ b/docs/clients/auth/oauth.mdx @@ -0,0 +1,116 @@ +--- +title: OAuth Authentication +sidebarTitle: OAuth +description: Authenticate your FastMCP client with servers using the OAuth 2.0 Authorization Code Grant, including user interaction via a web browser. +icon: window +--- + +import { VersionBadge } from "/snippets/version-badge.mdx" + + + + +OAuth authentication is only relevant for HTTP-based transports and requires user interaction via a web browser. + + +When your FastMCP client needs to access an MCP server protected by OAuth 2.0, and the process requires user interaction (like logging in and granting consent), you should use the Authorization Code Flow. FastMCP provides the `fastmcp.client.auth.OAuth` helper to simplify this entire process. + +This flow is common for user-facing applications where the application acts on behalf of the user. + +## Client Usage + + +### Default Configuration + +The simplest way to use OAuth is to pass the string `"oauth"` to the `auth` parameter of the `Client` or transport instance. FastMCP will automatically configure the client to use OAuth with default settings: + +```python {4} +from fastmcp import Client + +# Uses default OAuth settings +async with Client("https://fastmcp.cloud/mcp", auth="oauth") as client: + await client.ping() +``` + + +### `OAuth` Helper + +To fully configure the OAuth flow, use the `OAuth` helper and pass it to the `auth` parameter of the `Client` or transport instance. `OAuth` manages the complexities of the OAuth 2.0 Authorization Code Grant with PKCE (Proof Key for Code Exchange) for enhanced security, and implements the full `httpx.Auth` interface. + +```python {2, 4, 6} +from fastmcp import Client +from fastmcp.client.auth import OAuth + +oauth = OAuth(mcp_url="https://fastmcp.cloud/mcp") + +async with Client("https://fastmcp.cloud/mcp", auth=oauth) as client: + await client.ping() +``` + +#### `OAuth` Parameters + +- **`mcp_url`** (`str`): The full URL of the target MCP server endpoint. Used to discover OAuth server metadata +- **`scopes`** (`str | list[str]`, optional): OAuth scopes to request. Can be space-separated string or list of strings +- **`client_name`** (`str`, optional): Client name for dynamic registration. Defaults to `"FastMCP Client"` +- **`token_storage_cache_dir`** (`Path`, optional): Token cache directory. Defaults to `~/.fastmcp/oauth-mcp-client-cache/` +- **`additional_client_metadata`** (`dict[str, Any]`, optional): Extra metadata for client registration + + +## OAuth Flow + +The OAuth flow is triggered when you use a FastMCP `Client` configured to use OAuth. + + + +The client first checks the `token_storage_cache_dir` for existing, valid tokens for the target server. If one is found, it will be used to authenticate the client. + + +If no valid tokens exist, the client attempts to discover the OAuth server's endpoints using a well-known URI (e.g., `/.well-known/oauth-authorization-server`) based on the `mcp_url`. + + +If the OAuth server supports it and the client isn't already registered (or credentials aren't cached), the client performs dynamic client registration according to RFC 7591. + + +A temporary local HTTP server is started on an available port. This server's address (e.g., `http://127.0.0.1:/callback`) acts as the `redirect_uri` for the OAuth flow. + + +The user's default web browser is automatically opened, directing them to the OAuth server's authorization endpoint. The user logs in and grants (or denies) the requested `scopes`. + + +Upon approval, the OAuth server redirects the user's browser to the local callback server with an `authorization_code`. The client captures this code and exchanges it with the OAuth server's token endpoint for an `access_token` (and often a `refresh_token`) using PKCE for security. + + +The obtained tokens are saved to the `token_storage_cache_dir` for future use, eliminating the need for repeated browser interactions. + + +The access token is automatically included in the `Authorization` header for requests to the MCP server. + + +If the access token expires, the client will automatically use the refresh token to get a new access token. + + + +## Token Management + +### Token Storage + +OAuth access tokens are automatically cached in `~/.fastmcp/oauth-mcp-client-cache/` and persist between application runs. Files are keyed by the OAuth server's base URL. + +### Managing Cache + +To clear the tokens for a specific server, instantiate a `FileTokenStorage` instance and call the `clear` method: + +```python +from fastmcp.client.auth import FileTokenStorage + +storage = FileTokenStorage(server_url="https://fastmcp.cloud/mcp") +await storage.clear() +``` + +To clear *all* tokens for all servers, call the `clear_all` method on the `FileTokenStorage` class: + +```python +from fastmcp.client.auth import FileTokenStorage + +FileTokenStorage.clear_all() +``` \ No newline at end of file diff --git a/docs/deployment/authentication.mdx b/docs/deployment/authentication.mdx deleted file mode 100644 index 25789fdc0..000000000 --- a/docs/deployment/authentication.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Authentication -sidebarTitle: Authentication -description: Secure your FastMCP server with authentication. -icon: lock ---- -import { VersionBadge } from '/snippets/version-badge.mdx' - - - -This document will cover how to implement authentication for your FastMCP servers. - -FastMCP leverages the OAuth 2.0 support provided by the underlying Model Context Protocol (MCP) SDK. - -For now, refer to the [MCP Server Authentication documentation](/servers/fastmcp#authentication) for initial details and the [official MCP SDK documentation](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for more. diff --git a/docs/docs.json b/docs/docs.json index 677c743a8..a4c24b519 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -56,18 +56,24 @@ "servers/context" ] }, + { + "group": "Authentication", + "icon": "shield-check", + "pages": [ + "servers/auth/bearer" + ] + }, "servers/openapi", "servers/proxy", - "servers/composition" - ] - }, - { - "group": "Deployment", - "pages": [ - "deployment/running-server", - "deployment/asgi", - "deployment/authentication", - "deployment/cli" + "servers/composition", + { + "group": "Deployment", + "pages": [ + "deployment/running-server", + "deployment/asgi", + "deployment/cli" + ] + } ] }, { @@ -75,6 +81,14 @@ "pages": [ "clients/client", "clients/transports", + { + "group": "Authentication", + "icon": "user-shield", + "pages": [ + "clients/auth/bearer", + "clients/auth/oauth" + ] + }, "clients/advanced-features" ] }, diff --git a/docs/servers/auth/bearer.mdx b/docs/servers/auth/bearer.mdx new file mode 100644 index 000000000..712c55518 --- /dev/null +++ b/docs/servers/auth/bearer.mdx @@ -0,0 +1,183 @@ +--- +title: Bearer Token Authentication +sidebarTitle: Bearer Auth +description: Secure your FastMCP server's HTTP endpoints by validating JWT Bearer tokens. +icon: key +--- + +import { VersionBadge } from "/snippets/version-badge.mdx" + + + +Authentication and authorization are only relevant for HTTP-based transports. + + +Bearer Token authentication is a common way to secure HTTP-based APIs. In this model, the client sends a token (usually a JSON Web Token or JWT) in the `Authorization` header with the "Bearer" scheme. The server then validates this token to grant or deny access. + +FastMCP supports Bearer Token authentication for its HTTP-based transports (`streamable-http` and `sse`), allowing you to protect your server from unauthorized access. + +## Authentication Strategy + +FastMCP uses **asymmetric encryption** for token validation, which provides a clean security separation between token issuers and FastMCP servers. This approach means: + +- **No shared secrets**: Your FastMCP server never needs access to private keys or client secrets +- **Public key verification**: The server only needs a public key (or JWKS endpoint) to verify token signatures +- **Secure token issuance**: Tokens are signed by an external service using a private key that never leaves the issuer +- **Scalable architecture**: Multiple FastMCP servers can validate tokens without coordinating secrets + +This design allows you to integrate FastMCP servers into existing authentication infrastructures without compromising security boundaries. + +## Configuration + +To enable Bearer Token validation on your FastMCP server, use the `BearerAuthProvider` class. This provider validates incoming JWTs by verifying signatures, checking expiration, and optionally validating claims. + + +The `BearerAuthProvider` validates tokens; it does **not** issue them (or implement any part of an OAuth flow). You'll need to generate tokens separately, either using FastMCP utilities or an external Identity Provider (IdP) or OAuth 2.0 Authorization Server. + + +### Basic Setup + +To configure bearer token authentication, instantiate a `BearerAuthProvider` instance and pass it to the `auth` parameter of the `FastMCP` instance. + +The `BearerAuthProvider` requires either a static public key or a JWKS URI (but not both!) in order to verify the token's signature. All other parameters are optional -- if they are provided, they will be used as additional validation criteria. + +```python {2, 10} +from fastmcp import FastMCP +from fastmcp.server.auth import BearerAuthProvider + +auth = BearerAuthProvider( + jwks_uri="https://my-identity-provider.com/.well-known/jwks.json", + issuer="https://my-identity-provider.com/", + audience="my-mcp-server" +) + +mcp = FastMCP(name="My MCP Server", auth=auth) +``` + +### Configuration Parameters + +| Parameter | Type | Required | Description | +|-----------|------|----------|-------------| +| `public_key` | `str` | If `jwks_uri` is not provided | RSA public key in PEM format for static key validation | +| `jwks_uri` | `str` | If `public_key` is not provided | URL for JSON Web Key Set endpoint | +| `issuer` | `str` | No | Expected JWT `iss` claim value | +| `audience` | `str` | No | Expected JWT `aud` claim value | +| `required_scopes` | `list[str]` | No | Global scopes required for all requests | + +#### Public Key + +If you have a public key in PEM format, you can provide it to the `BearerAuthProvider` as a string. + +```python {12} +from fastmcp.server.auth import BearerAuthProvider +import inspect + +public_key_pem = inspect.cleandoc( + """ + -----BEGIN PUBLIC KEY----- + MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy... + -----END PUBLIC KEY----- + """ +) + +auth = BearerAuthProvider(public_key=public_key_pem) +``` + +#### JWKS URI + +```python +provider = BearerAuthProvider( + jwks_uri="https://idp.example.com/.well-known/jwks.json" +) +``` + + +JWKS is recommended for production as it supports automatic key rotation and multiple signing keys. + + +## Generating Tokens + +For development and testing, FastMCP provides the `RSAKeyPair` utility class to generate tokens without needing an external OAuth provider. + + +The `RSAKeyPair` utility is intended for development and testing only. For production, use a proper OAuth 2.0 Authorization Server or Identity Provider. + +### Basic Token Generation + +```python +from fastmcp import FastMCP +from fastmcp.server.auth import BearerAuthProvider +from fastmcp.server.auth.providers.bearer import RSAKeyPair + +# Generate a new key pair +key_pair = RSAKeyPair.generate() + +# Configure the auth provider with the public key +auth = BearerAuthProvider( + public_key=key_pair.public_key, + issuer="https://dev.example.com", + audience="my-dev-server" +) + +mcp = FastMCP(name="Development Server", auth=auth) + +# Generate a token for testing +token = key_pair.create_token( + subject="dev-user", + issuer="https://dev.example.com", + audience="my-dev-server", + scopes=["read", "write"] +) + +print(f"Test token: {token}") +``` + +### Token Creation Parameters + +The `create_token()` method accepts these parameters: + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `subject` | `str` | `"fastmcp-user"` | JWT subject claim (usually user ID) | +| `issuer` | `str` | `"https://fastmcp.example.com"` | JWT issuer claim | +| `audience` | `str` | `None` | JWT audience claim | +| `scopes` | `list[str]` | `None` | OAuth scopes to include | +| `expires_in_seconds` | `int` | `3600` | Token expiration time | +| `additional_claims` | `dict` | `None` | Extra claims to include | +| `kid` | `str` | `None` | Key ID for JWKS lookup | + + +## Accessing Token Claims + +Once authenticated, your tools, resources, or prompts can access token information using the `get_access_token()` dependency function: + +```python +from fastmcp import FastMCP, Context, ToolError +from fastmcp.server.dependencies import get_access_token, AccessToken + +@mcp.tool() +async def get_my_data(ctx: Context) -> dict: + access_token: AccessToken = get_access_token() + + user_id = access_token.client_id # From JWT 'sub' or 'client_id' claim + user_scopes = access_token.scopes + + if "data:read_sensitive" not in user_scopes: + raise ToolError("Insufficient permissions: 'data:read_sensitive' scope required.") + + return { + "user": user_id, + "sensitive_data": f"Private data for {user_id}", + "granted_scopes": user_scopes + } +``` + +### AccessToken Properties + +| Property | Type | Description | +|----------|------|-------------| +| `token` | `str` | The raw JWT string | +| `client_id` | `str` | Authenticated principal identifier | +| `scopes` | `list[str]` | Granted scopes | +| `expires_at` | `datetime \| None` | Token expiration timestamp | + diff --git a/src/fastmcp/client/__init__.py b/src/fastmcp/client/__init__.py index 9397be295..9483fb6e5 100644 --- a/src/fastmcp/client/__init__.py +++ b/src/fastmcp/client/__init__.py @@ -11,7 +11,7 @@ FastMCPTransport, StreamableHttpTransport, ) -from .auth import OAuth +from .auth import OAuth, BearerAuth __all__ = [ "Client", @@ -26,4 +26,5 @@ "FastMCPTransport", "StreamableHttpTransport", "OAuth", + "BearerAuth", ] diff --git a/src/fastmcp/client/auth/__init__.py b/src/fastmcp/client/auth/__init__.py new file mode 100644 index 000000000..6ec3ecf4b --- /dev/null +++ b/src/fastmcp/client/auth/__init__.py @@ -0,0 +1,4 @@ +from .bearer import BearerAuth +from .oauth import OAuth + +__all__ = ["BearerAuth", "OAuth"] diff --git a/src/fastmcp/client/auth/bearer.py b/src/fastmcp/client/auth/bearer.py new file mode 100644 index 000000000..0c38a11b0 --- /dev/null +++ b/src/fastmcp/client/auth/bearer.py @@ -0,0 +1,17 @@ +import httpx +from pydantic import SecretStr + +from fastmcp.utilities.logging import get_logger + +__all__ = ["BearerAuth"] + +logger = get_logger(__name__) + + +class BearerAuth(httpx.Auth): + def __init__(self, token: str): + self.token = SecretStr(token) + + def auth_flow(self, request): + request.headers["Authorization"] = f"Bearer {self.token.get_secret_value()}" + yield request diff --git a/src/fastmcp/client/auth.py b/src/fastmcp/client/auth/oauth.py similarity index 98% rename from src/fastmcp/client/auth.py rename to src/fastmcp/client/auth/oauth.py index 28c2bba84..43df9d442 100644 --- a/src/fastmcp/client/auth.py +++ b/src/fastmcp/client/auth/oauth.py @@ -392,12 +392,3 @@ async def callback_handler() -> tuple[str, str | None]: ) return oauth_provider - - -class BearerAuth(httpx.Auth): - def __init__(self, token: str): - self.token = token - - def auth_flow(self, request): - request.headers["Authorization"] = f"Bearer {self.token}" - yield request diff --git a/src/fastmcp/client/transports.py b/src/fastmcp/client/transports.py index 5ab1d9a9e..e8a32b018 100644 --- a/src/fastmcp/client/transports.py +++ b/src/fastmcp/client/transports.py @@ -36,7 +36,7 @@ from pydantic import AnyUrl from typing_extensions import Unpack -from fastmcp.client.auth import OAuth +from fastmcp.client.auth.oauth import OAuth from fastmcp.server.dependencies import get_http_headers from fastmcp.server.server import FastMCP from fastmcp.utilities.logging import get_logger diff --git a/src/fastmcp/server/auth/__init__.py b/src/fastmcp/server/auth/__init__.py index e69de29bb..9c3055c47 100644 --- a/src/fastmcp/server/auth/__init__.py +++ b/src/fastmcp/server/auth/__init__.py @@ -0,0 +1,4 @@ +from .providers.bearer import BearerAuthProvider + + +__all__ = ["BearerAuthProvider"] diff --git a/tests/auth/providers/test_bearer.py b/tests/auth/providers/test_bearer.py index ff127f727..aed70af71 100644 --- a/tests/auth/providers/test_bearer.py +++ b/tests/auth/providers/test_bearer.py @@ -6,7 +6,7 @@ from pytest_httpx import HTTPXMock from fastmcp import Client, FastMCP -from fastmcp.client.auth import BearerAuth +from fastmcp.client.auth.bearer import BearerAuth from fastmcp.server.auth.providers.bearer import ( BearerAuthProvider, JWKData, diff --git a/tests/auth/test_oauth_client.py b/tests/auth/test_oauth_client.py index 71db7fe47..be3328a07 100644 --- a/tests/auth/test_oauth_client.py +++ b/tests/auth/test_oauth_client.py @@ -5,7 +5,7 @@ import httpx import pytest -import fastmcp.client.auth # Import module, not the function directly +import fastmcp.client.auth.oauth # Import module, not the function directly from fastmcp.client import Client from fastmcp.client.transports import StreamableHttpTransport from fastmcp.server.auth.auth import ClientRegistrationOptions @@ -193,10 +193,10 @@ def headless_oauth(*args, **kwargs): raise ValueError("mcp_url is required") return HeadlessOAuthProvider(mcp_url) - with patch("fastmcp.client.auth.OAuth", side_effect=headless_oauth): + with patch("fastmcp.client.auth.oauth.OAuth", side_effect=headless_oauth): client = Client( transport=StreamableHttpTransport(streamable_http_server), - auth=fastmcp.client.auth.OAuth(mcp_url=streamable_http_server), + auth=fastmcp.client.auth.oauth.OAuth(mcp_url=streamable_http_server), ) yield client