# AWS Cognito OAuth 
FastMCP v2.14.5

Meet [Prefect Horizon](https://prefect.io/horizon?utm_source=gofastmcp&utm_medium=docs&utm_campaign=docs_banner&utm_content=sitewide_banner), the enterprise MCP gateway built by the team behind FastMCP.

These are the docs for FastMCP 2.0. [FastMCP 3.0](/content/getting-started/welcome/index.html) is now available.

## Configuration

### Prerequisites
Before you begin, you will need:
1. An **[AWS Account](https://aws.amazon.com/)** with access to create AWS Cognito user pools.
2. Basic familiarity with AWS Cognito concepts (user pools, app clients).
3. Your FastMCP server’s URL (can be localhost for development, e.g., `http://localhost:8000`).

### Step 1: Create an AWS Cognito User Pool and App Client
Set up AWS Cognito user pool with an app client to get the credentials needed for authentication:

1. Go to the **[AWS Cognito Console](https://console.aws.amazon.com/cognito/)** and ensure you’re in your desired AWS region.
2. Select **“User pools”** from the side navigation and click **“Create user pool”** to create a new user pool.

Define Your Application:
- **Application type**: Select **“Traditional web application”** (this is the correct choice for FastMCP server-side authentication).
- **Name your application**: Enter a descriptive name (e.g., `FastMCP Server`).

Configure Options:
- **Sign-in identifiers**: Choose how users will sign in (email, username, or phone).
- **Required attributes**: Select any additional user information you need.
- **Return URL**: Add your callback URL (e.g., `http://localhost:8000/auth/callback` for development).

### Step 2: FastMCP Configuration
Create your FastMCP server using the `AWSCognitoProvider`, which handles AWS Cognito’s JWT tokens and user claims automatically:

```python
from fastmcp import FastMCP
from fastmcp.server.auth.providers.aws import AWSCognitoProvider
from fastmcp.server.dependencies import get_access_token

auth_provider = AWSCognitoProvider(
    user_pool_id="eu-central-1_XXXXXXXXX",
    aws_region="eu-central-1",
    client_id="your-app-client-id",
    client_secret="your-app-client-secret",
    base_url="http://localhost:8000",
)

mcp = FastMCP(name="AWS Cognito Secured App", auth=auth_provider)

@mcp.tool
async def get_access_token_claims() -> dict:
    """Get the authenticated user's access token claims."""
    token = get_access_token()
    return {
        "sub": token.claims.get("sub"),
        "username": token.claims.get("username"),
        "cognito:groups": token.claims.get("cognito:groups", []),
    }
```

### Testing
#### Running the Server
Start your FastMCP server with HTTP transport to enable OAuth flows:
```bash
fastmcp run server.py --transport http --port 8000
```

### Testing with a Client
Create a test client that authenticates with Your AWS Cognito-protected server:

```python
from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp", auth="oauth") as client:
        print("✓ Authenticated with AWS Cognito!")

print("Calling protected tool: get_access_token_claims")
        result = await client.call_tool("get_access_token_claims")
        user_data = result.data
        print("Available access token claims:")
        print(f"- sub: {user_data.get('sub', 'N/A')}")
        print(f"- username: {user_data.get('username', 'N/A')}")
        print(f"- cognito:groups: {user_data.get('cognito:groups', [])}")

if __name__ == "__main__":
    asyncio.run(main())
```

### Production Configuration
For production deployments, ensure to configure `jwt_signing_key`, and `client_storage`:

```python
import os
from fastmcp import FastMCP
from fastmcp.server.auth.providers.aws import AWSCognitoProvider

auth_provider = AWSCognitoProvider(
    user_pool_id="eu-central-1_XXXXXXXXX",
    aws_region="eu-central-1",
    client_id="your-app-client-id",
    client_secret="your-app-client-secret",
    base_url="https://your-production-domain.com",
)

mcp = FastMCP(name="Production AWS Cognito App", auth=auth_provider)
```

### Features
#### JWT Token Validation
The AWS Cognito provider includes robust JWT token validation:
- **Signature Verification**: Validates tokens against AWS Cognito’s public keys (JWKS).
- **Expiration Checking**: Automatically rejects expired tokens.
- **Issuer Validation**: Ensures tokens come from your specific AWS Cognito user pool.
- **Scope Enforcement**: Verifies required OAuth scopes are present.

#### User Claims and Groups
Access rich user information from AWS Cognito JWT tokens:
```python
@mcp.tool
async def admin_only_tool() -> str:
    token = get_access_token()
    user_groups = token.claims.get("cognito:groups", [])

if "admin" not in user_groups:
        raise ValueError("This tool requires admin access")

return "Admin access granted!"
```

#### Enterprise Integration
Perfect for enterprise environments with:
- **Single Sign-On (SSO)**: Integrate with corporate identity providers.
- **Multi-Factor Authentication (MFA)**: Leverage AWS Cognito’s built-in MFA.
- **User Groups**: Role-based access control through AWS Cognito groups.
- **Custom Attributes**: Access custom user attributes defined in your AWS Cognito user pool.
- **Compliance**: Meet enterprise security and compliance requirements.