For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Restrict chat invocation
Create a role-based access control policy that allows users to chat with a particular agent.
By default, chatting with an agent is not permitted, even if a user can view the agent in the catalog. To chat with an agent, a user needs the invoke access level on the Deployment of that agent. You grant this access level with an RBACPolicy resource, and you can limit it to one agent. For how access levels work, see About RBACPolicy resources. For an overview of all access control layers, see About access control.
About this guide
In this guide, you allow the members of a developers group chat with the myagent agent. First, you give the group read-only access to the catalog and confirm that chat is forbidden. Then, you add an invoke grant for the agent and confirm that chat works. This guide creates the RBACPolicy resources in the default tenant, where the SuperAdmin acts as the admin and writes every policy. In a setup with several teams, the SuperAdmin writes only the first policy of each tenant, and tenant admins create policies for their teams. To give several teams their own tenants in one registry, see Isolate teams with tenants.
Before you begin
Set up an OIDC provider so that users can authenticate with the registry.
Install Solo Enterprise for agentregistry and the
arctlCLI.Port-forward the Solo Enterprise for agentregistry server on port 12121 if you have not done so already. The registry is not exposed externally by default, so you need port-forwarding to reach it from your local machine.
kubectl -n agentregistry-system port-forward svc/agentregistry-enterprise-server 12121:12121
Step 1: Create a Keycloak group and user
Use the Keycloak Admin REST API to create a developers group and a user who belongs to it.
Get an admin token for the Keycloak Admin REST API.
export KEYCLOAK_ADMIN_TOKEN=$(curl -s \ -d "client_id=admin-cli" -d "username=admin" -d "password=admin" \ -d "grant_type=password" \ "${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token" \ | jq -r .access_token)Create the
developersgroup.curl -s -X POST \ -H "Authorization: Bearer ${KEYCLOAK_ADMIN_TOKEN}" \ -H "Content-Type: application/json" \ "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/groups" \ -d '{"name": "developers"}'Create a
dev-useraccount and assign it to thedevelopersgroup.curl -s -X POST \ -H "Authorization: Bearer ${KEYCLOAK_ADMIN_TOKEN}" \ -H "Content-Type: application/json" \ "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/users" \ -d '{ "username": "dev-user", "email": "dev-user@example.com", "firstName": "Dev", "lastName": "User", "enabled": true, "credentials": [{"type": "password", "value": "password", "temporary": false}] }' export DEV_USER_ID=$(curl -s \ -H "Authorization: Bearer ${KEYCLOAK_ADMIN_TOKEN}" \ "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/users?username=dev-user" \ | jq -r '.[0].id') export DEVELOPERS_GROUP_ID=$(curl -s \ -H "Authorization: Bearer ${KEYCLOAK_ADMIN_TOKEN}" \ "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/groups?search=developers" \ | jq -r '.[0].id') curl -s -X PUT \ -H "Authorization: Bearer ${KEYCLOAK_ADMIN_TOKEN}" \ "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/users/${DEV_USER_ID}/groups/${DEVELOPERS_GROUP_ID}"Verify that the
developersgroup anddev-userwere created and the group assignment is in place.curl -s \ -H "Authorization: Bearer ${KEYCLOAK_ADMIN_TOKEN}" \ "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/groups" \ | jq '.[].name' curl -s \ -H "Authorization: Bearer ${KEYCLOAK_ADMIN_TOKEN}" \ "${KEYCLOAK_URL}/admin/realms/${KEYCLOAK_REALM}/users?username=dev-user" \ | jq '.[0].username'Example output:
"developers" "dev-user"
Step 2: Grant read access to the catalog
Without a policy, the dev-user user cannot see any object in the registry. In this step, you create an RBACPolicy that gives the developers group read access to agents, MCP servers, runtimes and deployments in the registry catalog created. In a later step, you add chat access to the same policy.
Log in to Solo Enterprise for agentregistry as the SuperAdmin, which is a user that matches the claim in your
rbac.superAdminPrincipalsHelm value. Only a SuperAdmin can write the first RBACPolicy of a tenant, because the registry denies every other user access until a policy grants it. This guide uses theadmin-useruser of theadminsgroup and the passwordpassword. The command uses thear-cli-passwordclient, which exchanges a username and a password for an access token, so you do not need a browser.export OIDC_ISSUER=$KEYCLOAK_ISSUER arctl user logout arctl user login \ --oidc-flow=password-credentials \ --oidc-client-id=ar-cli-password \ --oidc-username=admin-user \ --oidc-password=passwordCreate the RBACPolicy as the SuperAdmin. The policy belongs to the
defaulttenant, because it setsmetadata.namespace: default. Thedefaulttenant holds every object that has no namespace, including the catalog that you built in the prerequisites. The following example gives users of thedevelopersgroupviewaccess to agents, MCP servers, runtimes, and deployments.cat <<EOF | arctl apply -f - apiVersion: ar.dev/v1alpha1 kind: RBACPolicy metadata: name: developers namespace: default spec: principals: - all: - attribute: Groups values: [developers] grants: - name: view-agents accessLevel: view resource: agents - name: view-mcpservers accessLevel: view resource: mcpservers - name: view-runtimes accessLevel: view resource: runtimes - name: view-deployments accessLevel: view resource: deployments EOFExample output:
✓ RBACPolicy/developers createdVerify that the policy is created.
arctl get rbacpoliciesExample output:
NAME PRINCIPALS GRANTS developers 1 4
Step 3: Try to chat with the agent
Log out of the SuperAdmin session and log in to Solo Enterprise for agentregistry as the
dev-useruser with the passwordpassword. The user belongs to thedevelopersgroup that you created in the first step.export OIDC_ISSUER=$KEYCLOAK_ISSUER arctl user logout arctl user login \ --oidc-flow=password-credentials \ --oidc-client-id=ar-cli-password \ --oidc-username=dev-user \ --oidc-password=passwordInspect the JWT that is returned by Keycloak to confirm that the
developersgroup claim is in the token.arctl user info --show-tokens \ | jq -r '.access_token | split(".") | .[1] | @base64d | fromjson | {sub, email, Groups}'Example output:
{ "sub": "fbb5e028-4ef7-41de-8a6b-88365c26287d", "email": "dev-user@example.com", "Groups": [ "developers" ] }Open the Solo Enterprise for agentregistry UI and navigate to the
myagentagent. In the Agent Details card, click Open Chat.Try chatting with the agent. For example, you can ask it what it can do for you. Then, hit Enter and wait for the agent to reply. Verify that access to the agent chat is forbidden, because the policy grants only
viewaccess.
Step 4: Enable invocation access
As the SuperAdmin, add a grant with the invoke access level to the policy. The grant applies to Deployments of the myagent agent only, so users of the developers group can chat with this agent and no other agent.
Log out of the
dev-usersession and log in again as the SuperAdmin, with theadmin-useruser and the passwordpassword.export OIDC_ISSUER=$KEYCLOAK_ISSUER arctl user logout arctl user login \ --oidc-flow=password-credentials \ --oidc-client-id=ar-cli-password \ --oidc-username=admin-user \ --oidc-password=passwordUpdate the RBACPolicy. The following example keeps the
viewgrants and adds theinvokegrant. Thetargetconstraint limits theinvokegrant to Deployments of themyagentagent.cat <<EOF | arctl apply -f - apiVersion: ar.dev/v1alpha1 kind: RBACPolicy metadata: name: developers namespace: default spec: principals: - all: - attribute: Groups values: [developers] grants: - name: view-agents accessLevel: view resource: agents - name: view-mcpservers accessLevel: view resource: mcpservers - name: view-runtimes accessLevel: view resource: runtimes - name: view-deployments accessLevel: view resource: deployments - name: chat-with-myagent accessLevel: invoke resource: deployments constraints: - all: - attribute: target values: [myagent] EOFField Description spec.grants[].accessLevelinvokeallows a user to call a deployed agent without access to the configuration of the Deployment.managedoes not includeinvoke, so a user who can manage Deployments still needs this grant to chat.spec.grants[].resourceThe key deploymentsapplies the grant to Deployments. The access levelinvokeis available only for this key.spec.grants[].constraints[].all[]The attribute targetmatches the name of the object that the Deployment deploys. In this example, only Deployments of themyagentagent match. A constraint onnamewould match the name of the Deployment instead.Verify the policy.
arctl get rbacpolicy developers -o yaml
Step 5: Verify invocation access
Open the Solo Enterprise for agentregistry UI, logout, and log back in as the dev user with the
dev-userusername andpasswordpassword.Navigate to the
myagentagent. In the Agent Details card, click Open Chat.Chat with the agent. For example, you can ask it what it can do for you. Verify that this time, chatting with the agent is allowed and that you get a response back from your agent.