Skip to main content

Identity and access

Every person who uses AlphaAgent signs in through your own identity provider. This page follows a sign-in end to end for both consoles, lists the roles that decide what a signed-in person can do, and explains the two ownership models a Studio deployment can run under: standard, where each user sees only their own resources, and governed, where the deployment's resources are shared by everyone assigned to it.

Who this is for​

Identity administrators connecting Entra ID, and security engineers reviewing authorisation.

Before you start​

AlphaAgent federates through SAML. Two applications exist in your Entra ID tenant per Organisation: a SAML Enterprise Application for the Organisations console, created by your identity administrator during the install, and a multi-tenant application registration you create for Organisations' own Microsoft Graph calls. Each Studio deployment then gets its own SAML Enterprise Application, created by Organisations through Graph with that registration's credentials.

Sign-in to the Organisations console​

  1. The install prints the values your identity administrator needs for a non-gallery SAML application: the identifier urn:amazon:cognito:sp:<user pool id>, the reply URL https://<prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse, the sign-on URL, and the provider name AlphaAgentSSO. The application must send three claims, mapped by name: email, given_name and family_name.
  2. Your administrator assigns the users and groups who may reach the console and exports the federation metadata XML.
  3. The saml install step configures the Cognito user pool in your Organisations account with that metadata. From then on password sign-in is off for everyone; the console is reached only through your identity provider.
  4. The install seeds one break-glass owner row and prints the command to remove that user after you have verified sign-in.
  5. Console-bearing roles are also assigned on the console's own Enterprise Application, so a person who is granted a console role in Organisations is assigned to the application in Entra at the same time.

Sign-in to Studio​

Each Studio deployment has its own Cognito user pool with a SAML provider named AlphaAgentSSO. The load balancer adds authenticate-cognito to every listener rule except /api/v1, so an unauthenticated browser is redirected to sign in before it reaches any service. The services read the signed-in identity that the load balancer forwards; a request without it is refused.

How the SAML application for a deployment is created:

  • Connected tenant (the normal path). Under Identity Providers you create a multi-tenant application registration in your tenant with five Microsoft Graph application permissions (Application.ReadWrite.OwnedBy, Application.Read.All, User.Read.All, Group.Read.All, AppRoleAssignment.ReadWrite.All), grant admin consent, and store its client id and secret in the Organisations console as the platform setup credentials. Connect then sends you to Microsoft to consent for the tenant. For each deployment linked to that tenant, the saml step instantiates a non-gallery SAML Enterprise Application in your tenant through Graph, reads its federation metadata, and configures the deployment's user pool with it. That application requires assignment: a user who is not assigned is refused by Microsoft at sign-in (Entra ID exempts Global Administrators from assignment checks tenant-wide, so an administrator's own sign-in is not a test of the gate).
  • Manual metadata. Without a connected tenant, the saml step parks and waits for you to upload the metadata XML of an application you created yourself.

Assigning a person to a deployment is the StudioUser role grant in the Organisations console (Users, then Assign a role). The grant creates the app-role assignment on that deployment's Enterprise Application in your tenant, to the user or to a group. Revoking the grant removes the assignment. A grant to a group covers every current and future member.

Roles​

WhereRoleWhat it allows
Organisations (legacy tiers)owner, operator, viewerFull administration, day-to-day administration, read-only. Held in the admins table; the install seeds the first owner.
Organisations (built-in roles)For example FleetViewer, AccessAdministrator, ProgrammaticAccessViewer, ProgrammaticAccessAdministrator, LibraryViewer, LibraryContributor, LibraryManagerBundles of policies granted org-wide or on one resource. Built from the Roles and Policies screens; custom roles can be created.
Organisations, per deploymentStudioUserMay sign in to that Studio deployment. Counts against the deployment's seat cap.
Libraries, per LibraryContributor, ReaderContributor: create, read, pull and delete own items. Reader: read and pull. A Studio user can share to a Library only where they are a Contributor.
Studio, per deploymentEvery assigned userStandard: personal resources. Governed: shared resources. There are no roles inside Studio.
Programmatic access (governed only)API keyActs as the principal apikey:<key id> with the scopes on the key; never a human's identity.

Studio deployments also carry service principals: the services authenticate to each other with an internal key and pass the ownership checks as services, never as a user.

Per-user isolation in a standard deployment​

A standard deployment (ownership mode user) keeps every user's resources private:

  • Every row (agent, workflow, connector, knowledge graph, environment, conversation, run) is stamped with the creating user's identity. Lists return the caller's rows only.
  • A read, update or delete of another user's row answers 404, the same as a row that does not exist. The service does not answer 403, so a resource id cannot be used to learn that another user's resource exists.
  • An agent may pin only references (knowledge graph version, connector version, environment) that the same user owns; a reference outside that set is refused by name as if it did not exist.
  • Workspace files are read and written only under the caller's own prefix, users/<user id>/. The sandbox's per-invocation credentials carry the same prefix; see Sandbox isolation.
  • A run belongs to the user who started it; only that user can read or stop it.

The governed model​

A governed deployment (ownership mode deployment) is chosen once in the new-deployment wizard and cannot be changed later. Authentication is identical. What changes is scope:

CapabilityStandardGoverned
Lists of agents, workflows, connectors, environments, knowledge graphs, runsThe caller's ownDeployment-wide
Read, update, delete, run another user's resource404Allowed for every assigned user; a missing row is still 404
Pinned references on an agentMust be owned by the callerAny object in the deployment
Workspace filesOwn prefix onlyEvery user's files are readable ("Everyone's files" in the Files tab); writes still land only in the caller's own folder
RunsOwner onlyAny assigned user may read and stop, including runs started by an API key
Per-user caps (for example 256 workflows)Counted per userStill counted per user; resources are shared, quotas are not
PII redaction floor defaultOffMask
Programmatic APIRefused with not_governedAvailable once a key exists

Writes are attributed in both models: every row records who created it, and the Studio header shows a "Governed deployment" chip so users know resources are shared.

Steps: verify the identity chain​

  1. In Entra ID, open Enterprise applications and filter by AlphaAgent. You should see the console application your administrator created, the application registration you created for Graph, and one application per Studio deployment. Each Studio application has Assignment required set to yes.
  2. In the Organisations console, open Users, pick a person and confirm their StudioUser grants match their assignments in Entra.
  3. In Cognito in a Studio account, open the deployment's user pool. One identity provider, AlphaAgentSSO, of type SAML.
  4. Sign in to Studio as a non-administrator user who has no StudioUser grant for that deployment. Microsoft refuses the sign-in before Studio is reached. (A Global Administrator bypasses the assignment check, so do not test with one.)

What you should see​

  • No Cognito user with a password in either pool other than the break-glass owner until you remove it.
  • Every Studio sign-in recorded in your Entra sign-in logs against the deployment's application.
  • In a standard deployment, two users signed in side by side see different resource lists; in a governed deployment they see the same list.

Limits​

  • Each deployment has a seat cap for StudioUser grants, 20 by default; the Organisations console shows used and available seats.
  • The ownership mode is fixed at creation. Moving resources between a standard and a governed deployment is done by sharing through a Library.
  • Only SAML federation is supported for sign-in.

If something goes wrong​

  • A job fails with saml_configuration_failed: the metadata could not be applied to the user pool. The job's remediation text names the cause.
  • A job fails with saml_auto_provisioning_failed or entra_credentials_unavailable: Organisations could not create or read the deployment's Enterprise Application. Check the application credentials under Identity Providers, then retry the job.
  • A user sees a Microsoft error at sign-in: the user is not assigned to the deployment's application. Grant StudioUser in the Organisations console rather than assigning by hand in Entra, so the two stay in step.