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)

Reply via email to