php-sdk/docs/run/authorization.md

Authorization

The PHP MCP SDK provides OAuth 2.1 authorization support for HTTP transports, implementing the MCP Authorization specification.

Scope: what this SDK does and does not do

The MCP server is an OAuth 2.1 Resource Server. It validates the tokens it receives and may delegate the OAuth flow to your upstream Identity Provider. It is not an authorization server and it does not issue tokens.

Role	What it does	Status	Scope
Resource Server	Validates incoming bearer tokens, serves Protected Resource Metadata (RFC 9728), emits WWW-Authenticate	Supported (AuthorizationMiddleware, JwtTokenValidator, ProtectedResourceMetadata)	In scope
Delegation / proxy to an upstream AS	Forwards /authorize and /token to your existing IdP	Supported (OAuthProxyMiddleware)	In scope — delegation only
Authorization Server / Identity Provider	Mints its own tokens, registers clients, runs login and consent	Not implemented	Out of scope: being an authorization server / issuing tokens is out of scope

To issue tokens, front the MCP server with an external IdP (Keycloak, Auth0, Microsoft Entra ID, Okta) or run league/oauth2-server in your own application, and let the MCP server validate those tokens as a Resource Server. See adr/0001-oauth-authorization-server-out-of-scope.md.

Overview

Authorization in MCP is implemented at the transport level using PSR-15 middleware. The SDK provides:

• AuthorizationMiddleware - PSR-15 middleware that enforces bearer token authentication
• ProtectedResourceMetadataMiddleware - Serves RFC 9728 metadata at well-known endpoints
• OAuthProxyMiddleware - Delegates OAuth flows (/authorize, /token) to your upstream IdP; the SDK never issues tokens itself
• OAuthRequestMetaMiddleware - Bridges HTTP OAuth attributes to JSON-RPC request meta
• JwtTokenValidator - Validates JWT tokens using JWKS from OAuth 2.0 / OIDC providers
• OidcDiscovery - Discovers authorization server metadata from well-known endpoints

┌─────────────┐     ┌────────────────────┐     ┌─────────────────┐
│ MCP Client  │────▶│ AuthorizationMiddleware │────▶│  MCP Handlers   │
└─────────────┘     └────────────────────┘     └─────────────────┘
      │                      │
      │                      │ Validate JWT
      ▼                      ▼
┌─────────────┐     ┌─────────────────┐
│ Auth Server │◀────│ JwtTokenValidator│
│  (Keycloak, │     │    + JWKS       │
│   Entra ID) │     └─────────────────┘
└─────────────┘

Quick Start

use Mcp\Server;
use Mcp\Server\Transport\Http\Middleware\AuthorizationMiddleware;
use Mcp\Server\Transport\Http\Middleware\OAuthRequestMetaMiddleware;
use Mcp\Server\Transport\Http\Middleware\ProtectedResourceMetadataMiddleware;
use Mcp\Server\Transport\Http\OAuth\JwksProvider;
use Mcp\Server\Transport\Http\OAuth\JwtTokenValidator;
use Mcp\Server\Transport\Http\OAuth\OidcDiscovery;
use Mcp\Server\Transport\Http\OAuth\ProtectedResourceMetadata;
use Mcp\Server\Transport\StreamableHttpTransport;

// 1. Set up OIDC discovery and JWKS provider
$discovery = new OidcDiscovery();
$jwksProvider = new JwksProvider($discovery);

// 2. Create JWT validator for your OAuth provider
$validator = new JwtTokenValidator(
    issuer: 'https://auth.example.com/realms/mcp',
    audience: 'mcp-server',
    jwksProvider: $jwksProvider,
);

// 3. Create Protected Resource Metadata (RFC 9728)
$metadata = new ProtectedResourceMetadata(
    authorizationServers: ['https://auth.example.com/realms/mcp'],
    scopesSupported: ['mcp:read', 'mcp:write'],
);

// 4. Create middleware stack
$authMiddleware = new AuthorizationMiddleware(
    validator: $validator,
    resourceMetadata: $metadata,
);

$metadataMiddleware = new ProtectedResourceMetadataMiddleware(
    metadata: $metadata,
);

// 5. Create transport with middleware
$transport = new StreamableHttpTransport(
    $request,
    middleware: [
        ...StreamableHttpTransport::defaultMiddleware(),
        $metadataMiddleware,
        $authMiddleware,
        // Bridges the OAuth attributes onto the JSON-RPC request meta, which is
        // what makes them reachable from a handler (see Scope-Based Access Control).
        new OAuthRequestMetaMiddleware(),
    ],
);

// 6. Run server
$server = Server::builder()
    ->setServerInfo('Protected MCP Server', '1.0.0')
    ->setDiscovery(__DIR__, excludeDirs: ['vendor'])
    ->build();

$response = $server->run($transport);

Components

AuthorizationMiddleware

The main middleware that enforces authentication:

$middleware = new AuthorizationMiddleware(
    validator: $validator,         // AuthorizationTokenValidatorInterface
    resourceMetadata: $metadata,   // ProtectedResourceMetadata instance
    responseFactory: null,         // PSR-17 (auto-discovered)
);

Behavior:

Request	Response
Missing Authorization header	401 with WWW-Authenticate: Bearer resource_metadata="..."
Invalid/expired token	401 with error details
Valid token	Passes to next handler with OAuth attributes on request

ProtectedResourceMetadataMiddleware

Serves Protected Resource Metadata at configured well-known paths:

$metadataMiddleware = new ProtectedResourceMetadataMiddleware(
    metadata: $metadata,           // ProtectedResourceMetadata instance
    responseFactory: null,         // PSR-17 (auto-discovered)
    streamFactory: null,           // PSR-17 (auto-discovered)
);

JwtTokenValidator

Validates JWT access tokens:

$validator = new JwtTokenValidator(
    issuer: 'https://auth.example.com',  // Expected issuer claim
    audience: 'mcp-server',              // Expected audience (string or array)
    jwksProvider: $jwksProvider,          // JwksProviderInterface
    jwksUri: null,                       // Explicit JWKS URI (auto-discovered)
    algorithms: ['RS256', 'RS384', 'RS512'], // Allowed algorithms (this is the default)
    scopeClaim: 'scope',                 // Claim name for scopes
);

Request Attributes:

After successful validation, these attributes are added to the request:

Attribute	Description
oauth.claims	All JWT claims as array
oauth.scopes	Extracted scopes as array
oauth.subject	The sub claim
oauth.client_id	The client_id claim (if present)
oauth.authorized_party	The azp claim (if present)

ProtectedResourceMetadata

Represents RFC 9728 Protected Resource Metadata:

$metadata = new ProtectedResourceMetadata(
    authorizationServers: [              // Required: authorization server URLs
        'https://auth.example.com',
    ],
    scopesSupported: [                   // Optional: supported scopes
        'mcp:read',
        'mcp:write',
    ],
    resource: 'https://mcp.example.com', // Optional: resource identifier
    resourceName: 'My MCP Server',       // Optional: human-readable name
    metadataPaths: [                     // Paths to serve metadata (default: /.well-known/oauth-protected-resource)
        '/.well-known/oauth-protected-resource',
    ],
    extra: [                             // Optional: additional fields
        'custom_field' => 'value',
    ],
);

OidcDiscovery

Discovers OAuth/OIDC server metadata:

$discovery = new OidcDiscovery(
    httpClient: null,      // PSR-18 (auto-discovered)
    requestFactory: null,  // PSR-17 (auto-discovered)
    cache: $cache,         // PSR-16 cache (optional)
    cacheTtl: 3600,        // Cache TTL
);

// Discover metadata
$metadata = $discovery->discover('https://auth.example.com/realms/mcp');

// Get specific endpoints
$jwksUri = $discovery->getJwksUri($issuer);
$tokenEndpoint = $discovery->getTokenEndpoint($issuer);
$authEndpoint = $discovery->getAuthorizationEndpoint($issuer);

JwksProvider

Fetches and caches JWKS key sets:

$jwksProvider = new JwksProvider(
    discovery: $discovery,     // OidcDiscoveryInterface
    httpClient: null,          // PSR-18 (auto-discovered)
    requestFactory: null,      // PSR-17 (auto-discovered)
    cache: $cache,             // PSR-16 cache (optional)
    cacheTtl: 3600,            // JWKS cache TTL
);

JWT Token Validation

Keycloak

$validator = new JwtTokenValidator(
    issuer: 'https://keycloak.example.com/realms/mcp',
    audience: 'mcp-server',
    jwksProvider: $jwksProvider,
);

Microsoft Entra ID (Azure AD)

$tenantId = 'your-tenant-id';
$clientId = 'your-client-id';

$validator = new JwtTokenValidator(
    issuer: "https://login.microsoftonline.com/{$tenantId}/v2.0",
    audience: $clientId,
    jwksProvider: $jwksProvider,
);

Auth0

$validator = new JwtTokenValidator(
    issuer: 'https://your-tenant.auth0.com/',
    audience: 'https://api.example.com',
    jwksProvider: $jwksProvider,
);

Okta

$validator = new JwtTokenValidator(
    issuer: 'https://your-org.okta.com/oauth2/default',
    audience: 'api://default',
    jwksProvider: $jwksProvider,
);

Protected Resource Metadata

The ProtectedResourceMetadataMiddleware serves Protected Resource Metadata at configured paths, enabling clients to discover the authorization server:

{
  "authorization_servers": ["https://auth.example.com/realms/mcp"],
  "scopes_supported": ["mcp:read", "mcp:write"],
  "resource": "https://mcp.example.com/mcp"
}

Clients request this from /.well-known/oauth-protected-resource before authenticating.

WWW-Authenticate Header

On 401 responses, the middleware includes:

WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="mcp:read mcp:write"

Custom Token Validators

Implement AuthorizationTokenValidatorInterface for custom validation:

use Mcp\Server\Transport\Http\OAuth\AuthorizationTokenValidatorInterface;
use Mcp\Server\Transport\Http\OAuth\AuthorizationResult;

final class ApiKeyValidator implements AuthorizationTokenValidatorInterface
{
    public function __construct(
        private array $validKeys,
    ) {}

    public function validate(string $accessToken): AuthorizationResult
    {
        if (!isset($this->validKeys[$accessToken])) {
            return AuthorizationResult::unauthorized(
                'invalid_token',
                'Unknown API key'
            );
        }

        $keyInfo = $this->validKeys[$accessToken];

        return AuthorizationResult::allow([
            'api_key.name' => $keyInfo['name'],
            'api_key.scopes' => $keyInfo['scopes'],
        ]);
    }
}

// Usage
$validator = new ApiKeyValidator([
    'sk_live_abc123' => ['name' => 'Production', 'scopes' => ['read', 'write']],
]);

AuthorizationResult

Factory methods for different outcomes:

// Allow access with attributes
AuthorizationResult::allow(['user_id' => '123']);

// Deny - missing/invalid token (401)
AuthorizationResult::unauthorized('invalid_token', 'Token expired');

// Deny - valid token but insufficient permissions (403)
AuthorizationResult::forbidden('insufficient_scope', 'Requires admin scope', ['admin']);

// Deny - malformed request (400)
AuthorizationResult::badRequest('invalid_request', 'Malformed header');

Scope-Based Access Control

Checking Scopes in Handlers

#[McpTool(name: 'admin_action')]
public function adminAction(RequestContext $context): array
{
    // The OAuth attributes arrive on the request meta, under the `oauth` key.
    // This requires OAuthRequestMetaMiddleware in the transport's middleware stack.
    $meta = $context->getRequest()->getMeta() ?? [];
    $scopes = $meta['oauth']['oauth.scopes'] ?? [];

    if (!in_array('mcp:admin', $scopes, true)) {
        throw new \RuntimeException('Admin scope required');
    }

    // Perform admin action
    return ['status' => 'success'];
}

Using JwtTokenValidator::requireScopes

// In a custom middleware or handler
$result = $validator->validate($token);

if ($result->isAllowed()) {
    // Check for specific scopes
    $result = $validator->requireScopes($result, ['mcp:write']);
}

if (!$result->isAllowed()) {
    // Handle insufficient scope (returns 403)
}

Examples

Complete working examples are available in the examples/server/ directory:

Keycloak Example

cd examples/server/oauth-keycloak
docker-compose up -d

# Test credentials: demo / demo123

See oauth-keycloak/README.md

Microsoft Entra ID Example

cd examples/server/oauth-microsoft
cp env.example .env
# Edit .env with your Azure credentials
docker-compose up -d

See oauth-microsoft/README.md

Security Considerations

1. Always use HTTPS in production for token transmission
2. Validate audience claims to prevent token confusion attacks
3. Use short-lived tokens and implement token refresh
4. Cache JWKS to reduce latency but allow for key rotation
5. Never log tokens - log only non-sensitive claims like subject
6. Validate scopes before performing sensitive operations

Troubleshooting

"Invalid issuer" error

The iss claim in the token must exactly match the configured issuer URL, including trailing slashes.

"Invalid audience" error

Check the aud claim matches your configured audience. Some providers use the client ID, others use a custom URI.

JWKS fetch timeout

• Ensure network connectivity to the authorization server
• Consider using a cache to reduce dependency on the auth server
• Check firewall rules allow outbound HTTPS

Token expired

• Check clock synchronization between servers
• Tokens typically have a 5-minute clock skew tolerance
• Ensure clients refresh tokens before expiration