Install AlphaAgent Organisations into a new, empty AWS account, and give every AlphaAgent Studio deployment a new, empty AWS account of its own. Three reasons:
- It is AWS best practice to isolate each workload in its own account, with its own limits, billing view and permissions.
- Amazon Bedrock quotas are set per AWS account. Many users in one deployment share one quota and exhaust it; one account per deployment keeps each team's capacity its own.
- The blast radius is smaller. A problem in one deployment, or one team's mistake, cannot reach the others.
Sign in to the Organisations console with Entra ID
For the Entra ID administrator, who creates one non-gallery SAML enterprise application from the values step 2/12 printed, and the engineer running the install, who feeds its metadata to step 10/12 and runs doctor. Any SAML 2.0 provider works with the same three values and claims. Before you start: step 2/12 has printed the box below (python3 orgctl.py status --local reprints it).
Identifier (Entity ID) urn:amazon:cognito:sp:<UserPoolId>
Reply URL (ACS URL) https://<prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse
Sign-on URL https://<prefix>.auth.<region>.amazoncognito.com
SAML provider name AlphaAgentSSO
Required claims (mapped by name):
email <- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
given_name <- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
family_name <- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
AlphaAgentSSO is the fixed name the saml step gives the provider; it is not entered anywhere.
1. Create the enterprise application
- Entra admin center: Identity > Applications > Enterprise applications > New application > Create your own application. Name it ("AlphaAgent Organisations"), choose Integrate any other application you don't find in the gallery (Non-gallery), ignore the gallery suggestions, click Create.
- In the application: Single sign-on > SAML.
- Basic SAML Configuration > Edit: paste Identifier (Entity ID), Reply URL (Assertion Consumer Service URL) and Sign on URL from the box. The empty grid row becomes an input only when clicked; Tab lands in the optional Index cell; Save stays greyed until Identifier and Reply URL are filled.
- Attributes & Claims: the default
emailaddress,givennameandsurnameclaims are the three required; leave them. - Users and groups > Add user/group: add everyone who should reach the console, starting with the account whose address you gave the installer as break-glass owner (its Entra email claim must match that address exactly); the role is fixed to "User" and the picker accumulates selections.
- After Save (the signing thumbprint changes on the first Save): SAML Certificates > Federation Metadata XML > Download. Give the file (for example
~/Downloads/AlphaAgent-Organisations.xml) to whoever runs the installer. Entra offers no "test SSO" prompt; feedback appears only in the notification bell.
2. Hand the metadata to the saml step
Step 10/12 runs inside install, or alone as python3 orgctl.py saml. It reprints the box; if no break-glass owner is recorded it warns "Once SAML is configured below, sign-in goes through your identity provider only..." and asks Email for the break-glass administrator and first owner, printing "created <email>; a temporary password was emailed to them" and "<email> granted the owner role in alphaagent-org-admins". It then asks Path to the downloaded federation metadata XML file (drag the file in; the previous path is the default on a re-run). configure-saml.py creates or updates the AlphaAgentSSO provider, flips the app client to it alone and patches the listener rules; the app stack is redeployed. Step 11/12 prints "<email> already exists; left untouched".
Step 12/12 runs doctor; PASS on every group means the install is complete: Troubleshooting the install.
3. Sign in for the first time
Open https://<hostname>. The load balancer redirects to the sign-in domain, which sends you to Entra (the only provider after saml); with an Entra session already open there is no prompt at all. Sign in as the break-glass owner; the console shows "Signing you in..." and lands on Home. The session is a load-balancer cookie. Sign out sits in the footer beside your email and ends on "Your Organisations console session has ended."
What you should see
| Who | Home shows |
|---|---|
| The owner, and anyone later granted a fleet-viewing role | "A summary of your organisation's fleet.": Total deployments and a tile per status (Provisioning, Awaiting input, Healthy, Degraded, Failed, Deleting, Disabled, Uninstalled); "No deployments yet." on a new install; Accounts needing verification while any account is pending |
| Anyone assigned in Entra but holding no role | "Your fleet summary will appear here once you have access to it." and the card "You have access to nothing yet": "Ask an administrator to grant you a role in Identity & Access Management." |
Roles are granted on Users, groups and roles.
Notes
- The break-glass owner is a real user in the pool with a password, the first owner, and the only sign-in left if the identity-provider connection breaks ("Keep it while you rely on that safety net."). The installer prints its deletion command,
aws cognito-idp admin-delete-user --user-pool-id <pool id> --username <email> --region <region>; delete it only after single sign-on works for another owner. You do not sign in with it yourself: if the identity-provider connection breaks, contact Support and they restore access with you using this account. A rotated Entra certificate or new metadata is not a break: re-runpython3 orgctl.py saml, which asks for the metadata path on every run. - The three claims are mandatory. The break-glass email must match the
emailclaim Entra sends, spelt the same way. - Deleting
alphaagent-org-authremoves its users and changes the Entity ID; redo the Basic SAML Configuration andsamlafterwards. - When the console session expires, the overlay "Your session has expired" offers Sign in again; "any running deployment carries on regardless." Entra's two CSS sanitisation console errors on the SAML page are harmless.