Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: 11.3.0

Roles and Permissions

Overview​

HYPR AgentPass™ uses role-based access control. Every person who signs in holds at least one role, and works in one of them at a time. That role decides what they see in the console, and what they may change. An agent may use a tool when any role its supervisor holds allows it. See Controlling MCP Tool Access by Role.

AgentPass ships with roles that cover the common ways people work with the gateway. You can create your own when your organization divides responsibility differently.

A role can also be assigned to a service agent, an agent that runs with nobody at the keyboard. A service agent carries its own role instead of borrowing its owner's, so the role you give it decides its access. See Service Agents.

note

Managing roles is an administrator task. This page is for administrators who decide who can do what in the console.

Roles Available Out of the Box​

Open Oversight → People, and click the Roles tab to see the roles on your gateway. Each row shows the role's name and description, and whether it is a System role that AgentPass provides or a Custom role someone in your organization created. It also shows the identity provider values the role is Mapped from, how many permissions it grants, and how many people hold it.

AgentPass provides these system roles.

RoleWhat it is for
AgentPassAdminFull access to the console. Locked, so its name and permissions cannot change. It is the role that always keeps the ability to administer the gateway
AgentPassOperatorReads everything, and changes operational state: turning any agent off and on, deciding approvals and adding agents. It also creates and edits its own policies. It does not edit settings, connectors or roles, and it does not assign roles to people
AgentPassSupervisorManages the person's own agents, approvals, conversations and policies. Most people who supervise an agent need this role. It is the default for new users
The Roles tab of People, with each role's type, the identity provider values it is mapped from, its permissions and how many people hold it

AgentPassAdmin carries a lock icon, because its permissions are fixed. You can edit the other system roles to fit your organization.

How a Permission Works​

A permission is a single thing a role may do, expressed as an action on an area of the product, such as viewing agents, editing connectors, granting approvals or managing roles. Each permission a role holds also carries a scope, which decides how much of that area the role reaches.

ScopeWhat the role reaches
AllEvery record, whoever it belongs to
OwnOnly records belonging to the signed-in person: the agents they supervise, the approvals raised for them and their own conversations
No accessNothing. This applies when the role has not been granted the permission at all

Scope lets one role serve a whole organization. A supervisor granted Own on agents manages their own agents and sees nobody else's. An operator granted All sees the whole fleet. Not every permission makes sense at every scope. A person's own conversations, for example, are only ever personal. The editor shows every scope on each row and disables the scopes that do not apply.

Access is closed by default. A role reaches only what it has been granted. A custom role reaches a new area of the product only when you grant it. An upgrade can add permissions for a new area to the system roles, so review them after an upgrade.

Look at What a Role Grants​

To open a role, click Edit on it. The button reads View when your own role does not permit changes, and on the locked AgentPassAdmin role. The editor has four sections:

The Permissions section groups permissions by the product area they govern, so you can read a role top to bottom and see exactly what it reaches. Each permission is a row. You set its scope by choosing No access, Own or All.

A role's Permissions section, with permissions grouped by product area and a scope set on each

Create a Custom Role​

Create your own role when none of the supplied roles matches how your organization divides responsibility.

  1. On the Roles tab of Oversight → People, click New role.
  2. Optional: Under Start from, choose an existing role to copy its permissions.
  3. Enter a name and a description.
  4. Optional: Change the Precedence.
  5. Under Permissions, grant permissions and set their scopes.
  6. Click Create role.
  7. Optional: Under Agent tools permission, set which tools the role's agents may call, and under Identity provider, add the values that grant the role. Both become available once the role exists.

From then on, a custom role behaves exactly like a system role. You can assign it to people, or map identity provider values to it so assignment happens automatically. It governs agent tool access the same way.

Start from the job, not a supplied role

Build from what a person actually needs to do. An auditor who should read everything and change nothing is a few View grants at All scope. That is a much clearer role than a copy of an operator with permissions removed.

Map Identity Provider Values to a Role​

At each sign-in, AgentPass reads the role claim in the person's token and gives them every role that one of its values is mapped to. You choose the claim on the console's sign-in settings. See Populate Roles From Your Identity Provider.

  1. On the Roles tab of Oversight → People, click Edit on the role.
  2. Under Identity provider, add each value that should grant the role, such as the name of a directory group.
  3. Click Save in that section.

Mapping follows these rules:

  • Matching is exact and case-sensitive. Fraud.Reviewers and fraud.reviewers are different values.
  • A value grants one role. If the value is already mapped to another role, AgentPass names that role instead of saving.
  • Only a mapped value grants a role. A value that matches a role's name grants nothing unless it is mapped.
  • Someone with no mapped value gets the default role, so a new person can sign in and start working while their access is arranged.
After an upgrade

On upgrade, AgentPass maps each existing role to its own name, exactly as written. If your identity provider sends a role name in different capitalization, such as agentpassoperator, those people get the default role until you add that value to the role.

The Identity provider section of a role, listing the claim values that grant it

When Values Map to Several Roles​

A person whose values map to several roles holds all of them. Each role's Precedence orders them. AgentPassAdmin is 100, AgentPassOperator 50 and AgentPassSupervisor 10, and a new custom role starts at 25. You can set any role except AgentPassAdmin to a value from 1 to 99.

Until the person chooses otherwise, the console works in the role they hold with the lowest precedence, so they start with the least access. See Work in More Than One Role.

Assign a Role to Someone​

A person gets their roles in one of two ways:

  • From your identity provider. AgentPass assigns roles from the values mapped to them. Use this path at scale. See Map Identity Provider Values to a Role.
  • In the console. Use this path for a deliberate exception.

To assign roles in the console:

  1. On the Humans tab of Oversight → People, open the person's actions menu (⋮), and choose Change role.
  2. Select one or more roles.
  3. Click Change role.

The roles you set replace the roles from sign-in. They take effect on the person's next request, and later sign-ins do not change them.

To hand the person back to your identity provider, click Details on their row, and click Use identity provider roles. Their next sign-in sets their roles from their token again.

The Change role dialog, with roles to select and a note that the roles set here replace the roles from sign-in

Work in More Than One Role​

A person who holds several roles works in one of them at a time. The console grants only that role's permissions.

To switch, click your name at the top right of the console, and under Viewing as, choose a role. AgentPass remembers your choice for later sign-ins, for as long as you hold the role.

The account menu, with Viewing as listing the roles the person holds

The role you work in does not limit your agents. An agent may use a tool when any role its supervisor holds allows it.

Mapping changes and role switches are recorded in the audit trail.

Editing Roles Safely​

Know these behaviors before you reorganize your roles:

  • A role in use cannot be deleted. Reassign the people who hold it first. AgentPass tells you when a role still has assignees, instead of removing their access.
  • AgentPassAdmin cannot be edited or deleted. It is fixed so your gateway always keeps a role that can administer it.
  • Changes take effect on the next request. A person whose role or grants you change does not need to sign out and back in.