Authentication

Discovering Casdoor's OAuth Configuration

Casdoor implements RFC 9728 OAuth 2.0 Protected Resource Metadata, enabling MCP clients to automatically discover authentication requirements. Query the well-known endpoint to retrieve Casdoor's authorization server details:

curl https://your-casdoor.com/.well-known/oauth-protected-resource

The response indicates which OAuth authorization server protects the MCP resource:

{
  "resource": "https://your-casdoor.com",
  "authorization_servers": ["https://your-casdoor.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["openid", "profile", "email"]
}

For application-specific discovery, append the application name:

curl https://your-casdoor.com/.well-known/my-app/oauth-protected-resource

This returns metadata scoped to that specific application, useful when different applications have different authorization requirements.

Authentication Methods

MCP requests require authentication using any of the methods described in the Public API authentication documentation. The authentication method you choose affects which tools you can access.

Using an access token with scopes (recommended for automation):

curl -X POST https://your-casdoor.com/api/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Access tokens enforce scope-based authorization. The tools you can use depend on the scopes granted when the token was issued. This approach lets you create tokens with limited permissions for specific tasks.

Using client credentials (for service accounts):

curl -X POST https://your-casdoor.com/api/mcp \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Using session authentication (for interactive use):

Session-based authentication through browser cookies grants access to all tools without scope restrictions. This method is intended for interactive use and maintains compatibility with existing workflows.

Handling Unauthenticated Requests

Unauthenticated requests receive a JSON-RPC error response with a WWW-Authenticate header pointing to the OAuth protected resource metadata:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Unauthorized",
    "data": "Unauthorized operation"
  }
}

The response includes a WWW-Authenticate: Bearer realm="/.well-known/oauth-protected-resource" header, allowing compliant OAuth clients to automatically discover the authorization server configuration.