[ 
https://issues.apache.org/jira/browse/CAMEL-27144?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Claus Ibsen updated CAMEL-27144:
--------------------------------
    Fix Version/s: 4.24.0

> 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-ai, camel-mcp-server
>            Reporter: Serdar Gökay
>            Priority: Minor
>             Fix For: 4.24.0
>
>
> 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