Single sign-on (SAML)
Sign-in to AlphaAgent Studio is single sign-on only, federated to your own SAML 2.0 identity provider (IdP). There is no username/password and no self-signup — users authenticate through your IdP, and access is enforced at the load balancer before any request reaches Studio. This page explains the values you register in your IdP, the attributes Studio expects, and how to update federation later.
How sign-on works
A Cognito user pool in your account brokers federation between the load balancer and your IdP. When a user opens Studio, the load balancer redirects them to your IdP to authenticate; after a successful SAML response, the user reaches Studio.
Sessions last up to 12 hours before re-authentication is required.
Long-running work — building a Knowledge Graph or a Deep Traversal run — can take anywhere from a few minutes to several hours. If your IdP's session or assertion lifetime is shorter than the work, you can be signed out mid-run and see a 401 error. The run itself continues in the background and its results are saved, but you lose the live view until you sign back in. To avoid this, set the session duration during your SAML 2.0 custom-app setup to about 12 hours (matching Studio's own session cap). If you do hit a mid-run 401, sign in again and reopen the activity — see Sign-in (SAML) problems.
Service-provider values to register in your IdP
During the deploy's SSO step, the installer prints the exact values for your deployment. You register these in your IdP as a new SAML application:
| Value | Format |
|---|---|
| ACS / Reply URL (where the IdP posts the SAML response) | https://<your-cognito-prefix>.auth.<region>.amazoncognito.com/saml2/idpresponse |
| SP entity ID / Audience URI | urn:amazon:cognito:sp:<your-user-pool-id> |
The installer prints the concrete URLs with your prefix, region, and user pool filled in — use the printed values verbatim.
Required attributes
Configure your IdP to release these SAML attributes in the assertion so Studio can populate the signed-in user's profile. The mappings below use AWS IAM Identity Center's attribute syntax; if you use a different IdP, map each application attribute to the equivalent user field.
| User attribute in the application | Maps to (IAM Identity Center) | Format |
|---|---|---|
Subject (locked) | ${user:email} | emailAddress |
email | ${user:email} | emailAddress |
given_name | ${user:givenName} | unspecified |
family_name | ${user:familyName} | unspecified |
Map each of these in your IdP's attribute statement so they are sent on every sign-in.
Completing setup during deploy
The SSO step of the deploy walkthrough runs in this order:
- The installer prints the service-provider values above.
- You register Studio in your IdP using those values and configure the attribute mappings.
- You export your IdP's metadata (an XML document or metadata URL) and provide its path to the installer.
- The installer wires up federation — it configures the Cognito user pool to trust your IdP and sets the load balancer's listener to require SSO.
After this, all access to Studio goes through your IdP.
Provisioning users
Users are admin-provisioned shadows of your IdP identities — there is no public self-signup into Studio. A user becomes able to sign in once they exist in your IdP and are granted access to the Studio SAML application there. Manage who can use Studio through your IdP's normal access controls (groups, app assignments).
Updating federation later
If your IdP metadata changes (for example, a rotated signing certificate) or you need to adjust attribute mappings, re-run just the SSO step without redeploying everything:
python3 studioctl.py saml
This re-applies federation with your new metadata and leaves the rest of the deployment untouched.
Troubleshooting sign-in
- Loop back to the IdP / access denied — confirm the ACS URL and SP entity ID in your IdP exactly match what the installer printed, and that the user is assigned to the Studio app in your IdP.
- Missing name/email in Studio — check that
email,given_name, andfamily_nameare mapped and released by your IdP. - Certificate rotation — re-run
python3 studioctl.py samlwith the updated metadata.
See Troubleshooting for more.