Skip to content

Documentation

Access: roles and scopes

This guide explains who can do what in LEA Platform: the built-in and custom roles, how to give a team access to only some host groups, service accounts for integrations, how to check what one person can do, and how to review everyone's access.

Before you start

  • You need the Administrator role (or any role with the Users and sign-in permission) to change access. With the Audit log permission you can read the Roles and Reviews tabs, but not change anything.
  • Service accounts need the Manage tokens permission (Administrator).
  • Open Settings → Access.
  • People sign in through your identity provider. If single sign-on is not set up yet, start with Users, roles and sign-in.
  • Words used here: a host group is a group of hosts (see Groups); an identity is one person or application known from your identity provider.

How access works

Access in LEA Platform is a role given to someone, optionally limited to some host groups.

  • A role is a set of permissions, such as "view the fleet" or "run ad-hoc commands". LEA Platform ships six built-in roles that you cannot edit, and you can add your own custom roles.
  • A binding gives a role to someone. There are three kinds:
    • A role mapping gives the role to everyone whose identity provider sign-in carries a value, for example everyone in the Linux-Admins group.
    • A grant gives the role to one identity or service account.
    • A local user or API account carries its own role and scope, set in its user settings. See Give a local user a role and scope.
  • A scope limits a binding to some host groups. Leave it empty for everything.

When someone has several bindings, they get all of them together. A permission given for everything by one binding is everywhere; otherwise it applies to the groups of all their scoped bindings together.

No binding means no access: the person sees "You do not have access…" and an access request is recorded. See Approve an access request.

Built-in roles

A built-in role is a set of permissions that LEA Platform defines and keeps up to date; you choose which one each team gets.

RoleForCan do
ViewerEveryone who needs to look, and read-only appsSee the dashboard, compliance, results, hosts, groups, rules, functions (not their code), reports and agent logs. Use the AI assistant. Manage their own account and tokens.
AuditorCompliance officers and external auditorsEverything Viewer can do, plus the audit log and compliance reports with evidence.
OperatorSOC, helpdesk and site ITEverything Viewer can do, plus: handle notifications, run remedies, activate, deactivate, re-enroll and delete hosts, run ad-hoc commands, create and edit groups, assign existing rules to groups, remove results, decide approvals, and compliance reports.
EngineerRule and policy authorsEverything Operator can do, plus: create and edit rules (including secret values), roll out rule updates, rule packs and functions.
AdministratorPlatform ownersEvery permission, including settings, sign-in, users, tokens, integrations, the cluster and the license.
IntegrationSIEM, CMDB, BI and NAC lookupsSee the fleet, rules and compliance reports. Nothing else.

Viewer (read) is the older name of Viewer. Existing mappings and grants with read keep working and give the same access as Viewer.

The Roles tab of Settings → Access lists the roles. Click a row to see its permissions, grouped by what they let you do.

ColumnWhat it shows
RoleThe name of the built-in role, and its key as the API and audit log write it.
Can be scopedYes when the role can be limited to some host groups; No when it includes permissions that always apply to everything.
PermissionsHow many permissions the role includes. Click the row to list them.

Only Viewer, Operator, Integration and Viewer (read) can be scoped. Auditor, Engineer and Administrator include permissions that cannot be limited to groups (the audit log, rules, settings), so they are always for everything.

Permissions

A permission is one thing a person may do, such as editing groups or running ad-hoc commands; roles are built from permissions.

The Permissions table under the roles on the Roles tab lists every permission.

ColumnWhat it shows
PermissionThe name of the permission, and its key as the API and audit log write it.
ScopeWhether a binding can limit the permission to host groups. Groups or everything: it can; Everything only: never; Always everything: a scoped binding still gives it everywhere.
RiskWhat the permission lets you do: View, Change, Run on hosts or change rules, or Administer the platform.
PrivilegedYes for permissions that need extra care, such as ad-hoc commands, secrets and sign-in settings; these can also ask you to confirm it is you.

Some permissions are always given for everything, even by a scoped binding: using the AI assistant, your own tokens, your own account, viewing rules and viewing functions. Rules are shared by the whole fleet, so a scoped person still sees the full rule catalog.

Custom roles

A custom role is a set of permissions that you choose, for a team whose work does not fit a built-in role.

Custom roles are listed with the built-in roles on the Roles tab of Settings → Access, marked CUSTOM. You give them with role mappings and grants exactly like built-in roles.

ColumnWhat it shows
In useHow many role mappings, grants and local users give this role. A role in use cannot be deleted.
Can be scopedYes when every permission of the role can be limited to host groups.

Create a custom role

Example: a "Patch operator" may run remedies and handle notifications, nothing else.

  1. Open Settings → Access. On the Roles tab, click New role.
  2. Type a Label, for example Patch operator. The Key is filled in from it (patch_operator); you can change it now, but never later.
  3. Optionally type a Description that says who the role is for.
  4. Optionally pick Start from a role (optional) to copy the permissions of a built-in role, then remove what is not needed.
  5. Tick the Permissions. They are grouped by what they let you do; PRIVILEGED marks the ones that need extra care, and "everything only" marks the ones that cannot be limited to host groups.
  6. Click Create role. You may be asked to confirm it is you.

You should see: the role in the list with CUSTOM and In use 0. Under the permissions the dialog says whether the role "Can be limited to host groups", or which permissions prevent it.

Important: You can only put permissions in a role that you hold on all hosts yourself. Permissions you do not hold are greyed out, so nobody can create a role stronger than their own.

Change or delete a custom role

  • To change it, click the pencil icon on its row. The key stays; label, description and permissions can change. Everyone with the role gets the new permissions within a few seconds.
  • To delete it, click the bin icon. If the role is in use, the dialog lists the role mappings, grants and local users that give it; change or remove those on the Bindings tab first.

Give a team access to some host groups

Use a role mapping with a scope to give everyone in an identity provider group a role on some host groups only.

Example: the Linux team (identity provider group Linux-Admins) should run commands and manage hosts in the Linux-Prod group, and nowhere else.

  1. Open Settings → Access and click the Bindings tab.
  2. Click Add role mapping.
  3. In Identity provider, pick your provider.
  4. In Claim, pick or type the claim name, for example groups.
  5. In Value, type the exact value, for example Linux-Admins. For Microsoft Entra ID, use an app role value or a group object ID.
  6. In Role, pick Operator.
  7. In Scope, pick Linux-Prod. Pick more groups if needed. Nested groups are included.
  8. Optionally type a Label, for example Linux team, and click Save.

You should see: a new row with source MAPPING, groups = Linux-Admins, role Operator and scope Linux-Prod. The change applies at each person's next sign-in or re-check (by default within 10 minutes).

You can also add and edit role mappings in Settings → Single sign-on: click the provider, then Role mappings.

Note: If Scope is greyed out, the role you picked cannot be limited to groups. The text under the field names the permissions that always apply to everything.

Give one person access

Use a grant to give one identity a role, for example a contractor for 30 days.

  1. Open Settings → Access and click the Bindings tab.
  2. Click Add grant.
  3. In Identity, search by name, email or ID and pick the person. They must have signed in once (or been sent by SCIM provisioning).
  4. Pick the Role and, if needed, the Scope.
  5. Optionally fill in Expires after (days) and a Reason, then click Grant.

You should see: a row with source GRANT, the person's name and the expiry date.

You can also grant roles from Settings → Single sign-on → Identities: click Grant on the person's row. A person can hold several grants, each with its own role, scope and expiry. To see or remove them, click the person's row.

Read the bindings list

The Bindings tab lists every role mapping, grant and local user in one table. Use the search box to filter by claim value, name, role or group.

ColumnWhat it shows
SourceMAPPING for a role mapping of an identity provider, GRANT for a role given to one identity or service account, LOCAL for a local user or API account.
WhoFor a mapping, the claim and value and the identity provider; for a grant, the identity; for a local user, its name and account type. Click an identity to see its effective access.
RoleThe built-in or custom role this binding gives.
ScopeThe host groups the role is limited to, or Everything.
ExpiresWhen a grant stops working. Never for mappings and for grants without an expiry.
ReasonThe label of a mapping or the reason written for a grant.

Use the pencil icon to change a binding and the bin icon to remove it. Changing a grant replaces it with a new one, so its expiry starts again. The pencil icon of a local user opens its user settings; local users are removed from Settings → Local users.

Check what someone can do

The Effective access tab shows, for one identity, every binding that applies and the permissions they add up to.

  1. Open Settings → Access and click the Effective access tab.
  2. In Identity, search for the person, application or local user and pick it.

You should see:

  • Status, Role (the highest role), Database role and how many bindings apply.
  • A warning when something stops this identity from getting access, for example a disabled identity or too many groups from Microsoft Entra ID.
  • Where the access comes from: every matching role mapping and grant, or the role of a local user.
  • Permissions: every permission the identity has, with Everywhere or the host groups it applies to. Turn on Show missing to also list the permissions they do not have.
ColumnWhat it shows
FromThe claim value of a matching role mapping, or the reason of a grant.
DroppedPermissions of the role that this binding does not give because it is scoped and they only work for everything.
WhereEverywhere when the permission applies to the whole platform, otherwise the host groups it is limited to.
Database roleHow the database limits this identity: admin or read for everything, read_scoped when it only sees the hosts of its groups.

Bindings come from the identity provider claims of the person's last sign-in. If someone was just added to a group, they see the change after their next sign-in or re-check.

Ask "Can they…?"

Below the permissions, Can they…? checks one permission, optionally on one host or group.

  1. Pick a Permission, for example Ad-hoc commands.
  2. In Target, pick Anything, A host or A group, then pick the host or group.
  3. Click Check.

You should see ALLOWED or DENIED with the reason: allowed everywhere, allowed because the target is in their groups, denied because the target is outside their groups, or denied because none of their roles include the permission. The bindings that give the permission are listed under it.

Review who has access

The Reviews tab lists every identity with every binding that gives it access, and flags what needs a look.

Use it for a regular access review, for example every quarter, or when an auditor asks who can do what.

  1. Open Settings → Access and click the Reviews tab.
  2. Read the numbers at the top: Identities, Unused 90 days, Expiring in 14 days, Admins, Privileged and Dormant tokens. Click one to show only those rows; click it again, or Identities, to show everything.
  3. Use the search box to find a name, role or group.
  4. With the Users and sign-in permission, click a row to open that identity on the Effective access tab, then change or remove its binding on the Bindings tab.

You should see one row per binding: a person with a role mapping and a grant has two rows.

ColumnWhat it shows
IdentityThe person, application, local user or service account, with its kind, and its status when it is not active.
Last activeWhen the identity last signed in or last used a token, whichever is later. Never when it has not been used yet.
TokensHow many personal, CLI or service tokens of this identity can still be used.
FlagsWhat to check for this binding; the flags are listed below.
FlagMeaning
UNUSEDThe identity has not signed in or used a token for 90 days. Remove its access if nobody needs it any more.
EXPIRINGThe grant ends within 14 days. Extend it if the person still needs it, or let it end.
ADMINThe binding gives the Administrator role for everything. Keep this list short.
PRIVILEGEDThe binding includes a sensitive permission, such as ad-hoc commands, rule secrets, functions or sign-in settings.
DORMANT TOKENThe identity has a token that has not been used for 90 days. Revoke it if nothing uses it.

A local user is flagged UNUSED only after LEA Platform has recorded a sign-in or token use for it; calls with a user name and password are not recorded.

Export the review

Click Export CSV on the Reviews tab to download the whole review as a spreadsheet, with the same rows and flags. Keep it as evidence of the review, or send it to the team leads to confirm who still needs access.

Cells that start with =, +, - or @ get a leading ', so a spreadsheet does not run them as formulas.

See denied requests

Denied requests, last 7 days, under the review table, lists who was refused and for which permission.

It is shown to people with the Audit log permission. Every refusal is also in the audit log as a DENIED row.

ColumnWhat it shows
WhoThe person, application, local user or service account that was refused. With Users and sign-in, click it to open its effective access.
PermissionThe permission the request needed, or the reason it was refused when no single permission applies.
DenialsHow many times it was refused in the last 7 days. The same refusal is recorded at most once a minute.
LastWhen it was last refused.

Most denied above the table names the permissions refused most often. Many denials for one person usually mean they need a role; many for an application or service account usually mean its token is missing a permission.

Access reminders

People with the Users and sign-in permission for everything get reminders in the bell, under Security:

NotificationWhen
Access grant expiringA grant ends within 7 days. Short temporary grants of 7 days or less are not reminded. Opens the Reviews tab.
Unused accessOnce a week, when identities hold a role but were not used for 90 days. Opens the Reviews tab.
Service token expiringA service account token ends within 14 days. Opens the Service accounts tab.

Expiring reminders come again each day until the grant or token is renewed or ends. Mute them like any other notification; see Notifications.

Service accounts

A service account is an identity for an integration, such as a SIEM, a CMDB or a CI job, that works without any person's account.

Use a service account instead of a person's token or an API account with a password: it keeps working when the person leaves, it has its own role and audit trail, and its tokens always expire.

The Service accounts tab of Settings → Access lists them. Click a row to see its roles and tokens.

ColumnWhat it shows
OwnerThe team or person to contact about the integration, or who created it.
Roles and scopeThe roles its grants give, and the host groups they are limited to. NO ROLE means its tokens can do nothing yet.
TokensHow many active tokens it has (at most 2), and when one was last used.
StatusActive, or DISABLED: its tokens were revoked and it cannot get new ones until enabled again.

Create a service account

  1. Open Settings → Access and click the Service accounts tab.
  2. Click New service account.
  3. Type a Name, for example splunk-siem, a Description and the Owner. Click Create.
  4. Click the new row, then Grant role. Pick the Role (for example Integration), optionally a Scope and an expiry, and click Grant.
  5. Click New token and create a token as described below.

You should see: the service account with its role under Roles and scope and 1 of 2 under Tokens.

To stop an integration at once, click the disable icon on its row: its tokens are revoked and its roles stay. The bin icon deletes the service account with its tokens and roles.

Create and rotate service tokens

A service token (starts with lea_svc_) is the secret the integration sends; it acts as the service account, never as you.

  1. Click the service account's row, then New token.
  2. Type a Name, for example production, and pick Expires (service tokens always expire).
  3. Optionally fill in Allowed networks (optional): IP addresses or networks such as 10.20.0.0/16, separated by commas. The token is refused from any other address.
  4. Optionally limit the token under Limit this token (optional); see Narrow a token.
  5. Tick Manage the platform only for integrations that change users, sign-in, tokens or the cluster. The service account needs a role with Users and sign-in on all hosts for it, and you confirm it is you.
  6. Click Create token, copy the token and click Done. It is shown only once.
ColumnWhat it shows
LimitsWhat the token is narrowed to: a number of permissions, host groups and allowed networks, or the owner's full access.
Last usedWhen the token was last used, and from which address.

A service account holds at most 2 active tokens, so you can rotate without downtime:

  1. Create a second token.
  2. Put it in the integration.
  3. Wait until Last used moves to the new token.
  4. Click Revoke on the old one.

Convert an API account

An API account in Settings → Local users can become a service account with the same role, host groups and API limits.

  1. Open Settings → Local users.
  2. On the API account's row, click the convert icon (Convert to service account).
  3. Check the Service account name, optionally type the Owner, a Token name and Expires, and click Convert.
  4. Copy the token that is shown once.
  5. Put the token in the integration instead of the user name and password, then disable the API account.

You should see: the new service account on the Service accounts tab with the role of the API account. The API account keeps working until you disable it.

Narrow a token

A narrowed token is a personal access token or service token that can do only part of what its owner can do.

Narrowing is optional and set when you create the token, under Limit this token (optional):

  • Only some permissions: tick it and pick the permissions the token keeps. You can only pick permissions the owner holds.
  • Only these host groups: pick groups. The token only reaches hosts in these groups and their nested groups. Leave it empty to keep every group the owner can reach.

A narrowed token never does more than its owner can do at that moment: if the owner loses a permission or a group, the token loses it too. Lists of tokens show the limits, for example 2 PERMISSIONS and the group names.

Tip: Give each script or AI tool its own narrowed token, for example a token for a monitoring dashboard with only View the fleet.

What scoped users see

A scoped user only sees the hosts of their groups, and works on them as their role allows.

  • The left menu shows Scoped to: and the names of their groups.
  • Dashboards, compliance, results, hosts, notifications and reports only include hosts in their groups. Rules and functions are shown in full.
  • Groups that contain one of their hosts are shown too, so the rules those hosts run stay visible.
  • A scoped Operator can create and edit groups with hosts from their groups, assign existing rules to their groups and remove results of their hosts. Groups for all hosts or with a JSONPath filter, and groups used by other teams, can only be changed by someone with access to everything. A group they create is not added to their scope automatically.
  • Buttons for actions their role allows stay visible. If they act on something outside their groups, they get "This is outside the host groups you have access to."
  • Settings only shows the sections their permissions allow. A person without any of those permissions does not see Settings in the left menu.

If something goes wrong

  • "This is outside the host groups you have access to.": the host or group is not in the person's scope. Check on the Effective access tab, or add the group to the scope of their mapping or grant.
  • "Your role does not allow this action.": none of their roles include the permission. Give a role that does, with a mapping or a grant.
  • "This action needs access to everything, not only to some host groups.": the action works on the whole platform, so a scoped binding cannot allow it.
  • The scope field is greyed out: the role cannot be scoped. Pick Operator or Viewer, or give the role for everything.
  • A new mapping has no effect: the person has not signed in again yet, or the claim value differs. Open the person's access request or the Identities tab to see the claims the identity provider sent.
  • A scoped user does not see a new host: group membership is recalculated every few seconds; JSONPath memberships can take up to 15 seconds.
  • "You can only put permissions in a role that you hold on all hosts": remove the permissions named in the message, or ask someone who holds them to save the role.
  • A custom role cannot be deleted: it is in use. The delete dialog lists the bindings to change first.
  • "a service account can hold at most 2 active tokens; revoke one first": revoke the older token after the integration uses the new one.
  • "This token cannot be used from this network address": the token has Allowed networks and the call came from another address. Create a token with the right networks.
  • The Reviews tab says "Your role does not allow this action.": the review needs the Audit log or the Users and sign-in permission; denied requests need Audit log.
  • "the token owner does not hold: …" when creating a token: the token can only keep permissions its owner holds. For a service account, grant it a role with that permission first.

For more, see Troubleshooting.