OAuth Concepts Relevant for Authorization with the MCP Server and Setup Using Keycloak
Resource Owner The entity that owns the protected data. Usually the end user.
Client The application that wants to access the resource on behalf of the resource owner.
Authorization Server The server that authenticates the resource owner and issues access tokens to the client after successful authorization.
Resource Server The server that hosts the protected resources (APIs). It validates access tokens and serves requests if the token is valid.
AI Application An application powered by AI (with access to LLMs).
Downstream API Server The downstream server that provides the APIs. For example, Apache OFBiz.
Downstream API User The end user of the AI Application and of the Downstream API Server.
Authorization Server The server that provides Identity and Access Management (IAM) for the users of the AI Application and of the Downstream API Server.
MCP Server The middleware that bridges the AI Application to the Downstream API Server.
| MCP Roles | OAuth Roles |
|---|---|
| Downstream API Server | Resource Server |
| Downstream API User | Resource Owner |
| AI Application | Client |
| Authorization Server | Authorization Server |
| MCP Server | Resource Server Client (for token exchanges) |
Client A Client represents an application or service that relies on Keycloak for authentication and authorization. It defines how the application interacts with Keycloak (protocol, redirect URIs, credentials) and is the context in which client-specific roles and permissions are defined. Client is a generalization of the entities OAuth Resource Server and OAuth Client.
Client Scope A Client Scope represents a reusable set of configuration elements that can be applied to one or more Clients. It defines which claims, roles, and protocol mappings are added to tokens issued for a client, enabling consistent authorization and token content across applications.
Role A Role represents a named authorization concept that expresses permissions or responsibilities within a Client or at realm level. Roles can be assigned to Users directly or indirectly and are used to control access to protected resources.
User A User represents an identity managed by Keycloak that can authenticate and interact with Clients. A User may be assigned roles and attributes that determine what actions they are allowed to perform within applications.
Mapper A Mapper represents a configuration element that transforms or maps user data, roles, or other information into protocol-specific claims included in tokens. Mappers are executed in the context of Clients or Client Scopes to control how identity and authorization data are exposed to applications.
OAuth Resource Server definition for a Role
User participation in a Role
Mapper execution within a Client Scope
Role inclusion within a Client Scope
Client Scope as a context for OAuth Client
- Create a new realm and switch to it (e.g. OFBiz)
- In config.json of the MCP Server, set the AUTHZ_SERVER_BASE_URL parameter to match the URL of the Keycloak realm (e.g. http://localhost:8081/realms/OFBiz if Keycloak runs locally on http port 8081)
- Create a new Client for the MCP Server. Note down the client id (e.g. mcp-server) because you must set the MCP_SERVER_CLIENT_ID configuration parameter with this value (this value will be set as the "aud" claim in the access token and will be verified by the MCP server).
- Define a role in it (e.g. mcp-server-role) to complete the configuration of the MCP Server as an OAuth Resource Server
- Create a new Client Scope (e.g. "mcp:call-tools") that provides the context to MCP Clients (such as the ones in MCP Inspector, mcp-remote, Claude, etc...)
- Enable the flag "Display on consent screen" (optional)
- Enable the flag "Include in token scope"
- Set the type to "Default"
- Configure a new mapper of type "Audience Resolve" (make sure the flag "Add to access token" is enabled)
- In the Scope tab, assign as a client role, the role defined by the MCP Server's Client (as OAuth Resource Server)
- In order to allow Dynamic Client Registration (DCR), go to Clients > Client registration
- delete the Trusted Host policy if you wish to allow DCR from all host clients
- edit the Allowed Registration Web Origin policy to allow DCR from browser-based clients by Origin (or set it to * to allow all Origins). For example, this is required for DCR by the MCP Inspector
- Create a new Client for the Downstream API Server. Note down the client id (e.g. apache-ofbiz-api) because you must set the BACKEND_API_AUDIENCE configuration parameter with this value (this value will be set as the "aud" claim in the access token for the Downstream API Server that will verify it).
- There is no need to set any Authentication flow for this client as it represents only an OAuth Resource Server.
- Define a role in it (e.g. apache-ofbiz-api-role) to complete the configuration of the Downstream API Server as an OAuth Resource Server
- Configure the Downstream API Server to use Keycloak for token verification. In case of Apache OFBiz as the Downstream API Server, add to the Apache OFBiz's security.properties configuration file the following settings:
- security.token.issuer equal to the value set in AUTHZ_SERVER_BASE_URL (e.g., security.token.issuer=http://localhost:8081/realms/OFBiz)
- security.token.audience equal to the value set in BACKEND_API_AUDIENCE (e.g., security.token.audience=apache-ofbiz-api)
- Create a new Client Scope (e.g. "ofbiz:use-api") that provides the context to the MCP Server as an OAuth Client for token exchanges
- You can leave the type as None
- Make sure that the flag "Include in token scope" is enabled; in this way the Client Scope Name (e.g. "ofbiz:use-api") will be set as a scope in the token; you must set this value in the TOKEN_EXCHANGE_SCOPE parameter setting
- In the Scope tab, assign as a client role, the role defined by the Downstream API Server's Client (as OAuth Resource Server)
- Configure the required mappers to be executed so that the exchanged access token contains all claims needed for validation by the Downstream API Server
- the mapper "audience resolve" is required to add, in the "aud" claim of the token, the Client id of the Downstream API Server
- you can add mappers of type "User Attribute" to map custom user attributes to token claims as required by the Downstream API Server (e.g. for Apache OFBiz, User Attribute: username ; Token Claim Name: userLoginId)
- Edit the Client of the MCP Server (e.g. mcp-server) to configure the settings needed to act as an OAuth Client capable of requesting token exchanges
- Enable the "Client authentication" flag to set the confidential access for the client (this is required to enable the the Standard Token Exchange)
- Under "Authentication flow", select "Standard Token Exchange"
- Under the "Credentials" tab, generate a Client Secret and set in the MCP_SERVER_CLIENT_SECRET parameter
- Under the "Client scopes" tab, add as "Optional" the newly created Client Scope (e.g. "ofbiz:use-api") that provides the context to the MCP Server as an OAuth Client for token exchanges
- Create user(s)
- Set credentials.
- Under Role Mapping, assign to the user all Client Roles defined by the Clients that represent OAuth Resource Servers (e.g. mcp-server-role and, in case of token exchange, apache-ofbiz-api-role).
- Go to Realm settings > User profile
- Fine tune the information that users must provide
- Go to Realm settings > Sessions
- Set the duration of SSO Sessions (for refresh tokens)
- Set the duration of Offline Sessions (for offline access refresh tokens)
- Go to Realm settings > Tokens
- Set the Access Token Lifespan (for access tokens)
- Go to Clients and select the Client that represents the MCP Server, then select Advanced
- Set the Access Token Lifespan (for exchanged refresh tokens)