Serdar Gökay created CAMEL-27144:
------------------------------------
Summary: camel-ai-tool - allowedRoles option: a tool route names
the roles its caller needs
Key: CAMEL-27144
URL: https://issues.apache.org/jira/browse/CAMEL-27144
Project: Camel
Issue Type: New Feature
Components: camel-mcp-server, camel-ai
Reporter: Serdar Gökay
h2. Problem
A tool route served by camel-mcp-server knows who calls it. Since CAMEL-25405
the bridge puts the authenticated caller's name and roles on the tool exchange
({{CamelMcpSecurityPrincipalName}}, {{CamelMcpSecurityPrincipalRoles}}), read
from the first of the token's {{roles}}, {{realm_access.roles}} and {{groups}}
claims that is an array. {{roles}} and {{groups}} are the names RFC 9068
section 2.2.3.1 gives a user's authorization outside delegation;
{{realm_access.roles}} is Keycloak's own.
To say "only finance may call this tool" today, a user has two ways: an
{{AuthorizationPolicy}} class written in Java, with one bean for each set of
roles, or an OPA policy that is handed the property ({{includeProperties}}) and
a Rego rule on a policy server. Both are the right tool for a rule with
attributes. For the plain case, a role for each tool, both are heavy, and
neither leaves the requirement where tooling can read it.
{{camel.server.mcp-required-scopes}} (CAMEL-26356) answers what the client
application may do, for the whole endpoint. What the user may do, for each
tool, has no declarative form. The MCP specification asks a server to implement
proper access controls for its tools, and lists insufficient permissions next
to invalid scopes as a reason to refuse.
h2. Proposal
Two options on the ai-tool endpoint. Set on the component, they are the default
for every tool route, as with the other options. Neither changes an existing
route.
* {{allowedRoles}}: comma-separated role names. The caller needs one of them.
The name, type and levels are those of camel-undertow's {{allowedRoles}}; the
meaning is that of {{jakarta.annotation.security.RolesAllowed}}.
* {{allRolesRequired}} (default false): the caller needs all of them. The name
is the one {{ShiroSecurityPolicy}} and {{KeycloakSecurityPolicy}} use. The
default is false, as in Shiro and as {{@RolesAllowed}} means;
{{KeycloakSecurityPolicy}} defaults to true.
{noformat}
- route:
from:
uri: ai-tool:orderCosts
parameters:
description: "Costs of a production order"
allowedRoles: finance,controlling
steps:
- to:
uri: bean:costs
{noformat}
Behaviour:
* The check runs at the seam {{authorizationPolicy}} uses in
{{AiToolConsumer}}: in front of the route, in place before the tool is
registered.
* The caller's roles are read only from the exchange property
{{CamelMcpSecurityPrincipalRoles}}, never from a header or a tool argument. A
call without that property is refused. So a tool with {{allowedRoles}} refuses
every call where nothing sets the property: over stdio, on a server without
authentication, and on a runtime whose MCP engine does not set it. Tried on the
other two runtimes: on Spring Boot the engine sets it since CAMEL-26360
(Streamable transport, roles from Spring Security authorities) and the option
works; on Quarkus it does not yet (camel-quarkus PR 9509), so every such tool
refuses there.
* A refusal is the existing one: {{CamelAuthorizationException}}, the short
refusal to the model, the WARN and {{AiToolAuthorizationDeniedEvent}}. The log
names the tool, the roles it asks for and the caller; the model is not told the
roles.
* An {{allowedRoles}} that is set but names no role, such as a property
placeholder that resolves to an empty value, refuses every call. The security
model asks for this: "An unconfigured check, or a check with nothing to check,
must fail closed, not disappear". Of its two forms, fail closed or refuse to
start, the change takes the first, as camel-undertow does when roles are set
and nothing can check them: the route starts and a WARN at start names the
tool. Say if you prefer the start to fail.
* Not set means not written, or an optional placeholder whose property is
absent. The component's value then applies; with none there is no check, as
today. An endpoint can replace the component's roles with its own, but cannot
remove the check.
* With {{authorizationPolicy}} set as well, both must pass: the roles first,
then the policy, for example a Cedar or OPA policy for a rule with attributes.
* On the langchain4j-agent, openai and spring-ai-chat paths the calling route
sets the same property before the agent runs. Documented.
h2. Why an option, next to the policies
* No Java and no policy server: one line in YAML, XML or camel-jbang.
* The requirement is part of the endpoint. The catalog validates it, a route
dump and the route dev console show it, and tooling can answer "which tool
needs which role" without making a call.
* It is the declaration later work needs: a {{tools/list}} that leaves out what
the caller may not call (the MCP draft lets the tool set vary by the
authorization presented on the request), and the same shape for scopes for each
tool with the {{insufficient_scope}} challenge.
h2. One question on CAMEL-25405
The options read {{CamelMcpSecurityPrincipalRoles}}, and the documentation
tells a langchain4j-agent route to set that property itself, where no MCP is
involved. The property is not released yet (4.24.0). If a name without "Mcp" is
wanted, this is the moment; I have not renamed it here.
h2. Not in this issue
* A switch that closes every tool nobody guarded. I file it as its own issue.
* Scopes for each tool, and filtering {{tools/list}}.
* The Quarkus engine, which does not carry the caller's roles yet
(camel-quarkus PR 9509). The camel-ai-tool starter of camel-spring-boot needs
its usual regeneration for the component property; until then Spring Boot
ignores {{camel.component.ai-tool.allowed-roles}} silently, while the endpoint
option works.
Tested with unit tests and against a real Keycloak 26.8 (realm roles, client
roles and groups through mappers, role-less and unauthenticated callers,
parallel calls). I can send a PR.
_Claude Code on behalf of etzel-mes_
--
This message was sent by Atlassian Jira
(v10.3.26#10030026)