Access & identity

Access in aamp is a set of role assignments. Each one gives a user or a group a role on a scope. Identities and group memberships can come from your directory through single sign-on, while additional policies and knowledge reader rules can only narrow what roles allow.

Roles, scopes and assignments

An assignment binds one role to one scope: a concrete resource, or the whole installation where the role permits it. Assignments to a user and to the user's groups add together. Every protected route, stream and background job is checked host-side by an embedded Open Policy Agent (OPA) engine. Errors, timeouts and unknown operations deny.

Scope types are agent, workflow, script, ingress, tool_profile, knowledge_source, knowledge_collection, dataset, data_product, integration and provider. Every signed-in user can also manage their own profile, personal library and Inbox.

The installation root is a protected local account whose status is independent of role assignments. It cannot be disabled, deleted or replaced through user administration, and a forgotten root password is reset offline with aampctl auth recover-root, without the identity provider.

Custom roles

Open Settings → Roles. Built-in roles are read-only; Create a copy starts a custom draft. A new role has a name, a description, allowed scope types and an explicit list of actions. For example, an Agent reviewer can hold agent.view and agent.test without agent.edit or agent.publish.

• Save draft changes no access.
• Validate and preview lists added and removed actions, scope changes and the affected users, including current members of affected groups.
• Publication is confirmed with your local password or Confirm with SSO. The proof is single-use, valid for five minutes and bound to that exact change.
• Assign the published role from Users → Access or Groups → Access. A later publication updates every existing assignment of the role.
• Wildcards and unknown actions are rejected. New application actions are never added to custom roles automatically.
• Restoring a prior version creates a new immutable revision.

Single sign-on (OIDC)

aamp signs users in through an OpenID Connect provider, using the Authorization Code flow with mandatory PKCE (S256). Microsoft Entra ID, or Keycloak in front of Active Directory, are typical choices. The host operator configures one active provider in a JSON file passed with --oidc-config-file; the client secret is referenced from the encrypted secret store and never written into the file. The sign-in page then offers the provider next to local login.

• Admission rules combine: allowed_tenants (Entra tid), allowed_subjects and allowed_email_domains. allow_signup must be set explicitly to create accounts on first login.
• A new SSO account has no password and no direct roles; access comes from mapped groups or explicit assignments.
• An existing local account is linked explicitly from Profile → Single sign-on, keeping its ID, memberships and grants.
• session_seconds defaults to 8 hours. aamp does not request offline access and does not keep access or refresh tokens.
• A local block is authoritative: a successful IdP login does not undo it. Local root login keeps working when the IdP is unavailable.

Mapping directory groups and App Roles

Group membership stays where you govern it today: Active Directory, Entra ID, or an IAM or IGA system that manages directory groups. In aamp you create local groups under Settings → Groups, give them role assignments, and map stable external identifiers to them:

{
  "account_max_age_seconds": 900,
  "membership_max_age_seconds": 900,
  "group_mappings": [
    {"claim": "groups", "external_id": "EXTERNAL-GROUP-ID", "group_id": 12},
    {"claim": "roles",  "external_id": "Reports.Reader",    "group_id": 13}
  ]
}

• A groups value or an Entra App Role in the roles claim maps to a local group, whose assignments decide the permissions. Entra directory roles (wids) are ignored.
• Mappings use stable identifiers, not display names. Up to 200 mappings and 200 values per claim.
• External memberships are stored apart from manual ones and shown with the oidc source. Removing one never removes a local membership or a direct grant.
• A missing, null or malformed claim, or a group overage indicator, refuses login instead of being read as an empty list.
• Account and membership evidence is valid for 15 minutes by default (60 s to 24 h). After that, new requests and running work stop until the user signs in again.
• A newly observed administrative membership requires authentication no older than five minutes.
• Mapping changes apply at startup and require affected users to sign in again. Logs → Access Audit records mappings, reconciliations and incomplete observations.

Additional policies (OPA / Rego)

Open Settings → Policies to write restrictions on Agent use in Rego. The contract is aamp.policy.agent-use/v1, of kind additional_restriction: a policy can deny what roles allow, never grant. The subject is a user or an Ingress, and the channel is one of gui, api, webwidget, script, scheduler, assistant or internal. This policy restricts members of group 7 to the GUI and leaves other users unchanged:

package aamp_custom
import rego.v1

default allow := false
restricted if { some m in input.memberships; m.group_id == 7 }
allow if { not restricted }
allow if { input.context.channel == "gui" }

• Up to 64 test cases with expected results. Compilation and every test must pass before publication.
• Under Attachments you attach the policy to specific Agents. The preview evaluates current users and real API and WebWidget Ingresses, up to 2,000 decisions.
• The policy applies to the Agent’s current and historical releases, and to Script and Scheduler calls of that Agent.
• Limits: 32 KiB of Rego, 100 rules, 20 ms evaluation. Only deterministic built-ins are available, with no access to secrets.

Knowledge reader restrictions

Open a knowledge source and choose Readers to restrict the entire source or a single file to selected users or groups, optionally per channel. A file must satisfy its own rule and the source rule. A reader rule never grants Agent access.

• Full-text and semantic search filter unauthorized chunks before ranking, so they never reach the model.
• Citations, linked chunks, previews and original downloads check the same rules.
• A file rule follows the stable document ID and survives reindexing and restores.
• A conversation keeps the union of the knowledge it has used. Losing a required reader right blocks further turns in that conversation.

Delegated administration

access_admin and policy_admin grant nothing until a platform administrator sets a ceiling under Roles → Delegations: concrete resources, allowed role keys, delegable operations, editable groups and manageable definitions. Empty lists grant nothing. A delegated administrator cannot grant a broader role, edit a group that carries broader grants, manage their own delegation, or grant root or platform administration. Holding an action never implies permission to grant it.

Describe access with the Assistant

Describe access with Assistant in Roles or Policies turns a sentence such as “Finance can use the Reports Agent only through the GUI” into a proposal of assignments, roles, Rego and tests. The host validates every reference and simulates the result on real users, groups and Ingresses. The proposal is private to its author and is activated as a whole, in one transaction, only after fresh password or SSO confirmation. Account and SSO changes, global administrative roles and the author’s own access remain manual.

Audit and revocation

• Logs → Access Audit records drafts, publications, restores, attachments, delegations and mappings with the actor and before and after state.
• Access explanations and simulations show which assignment or policy revision produced a decision.
• Running Agent turns, streams and background workers recheck access every 250 ms. Unauthorized work stops within two seconds of the change.
• At startup aamp verifies active role and policy versions. Invalid active state stops startup instead of falling back to an older, less restrictive revision.