Before you start
- Access to the AWS Management Console (opens in a new tab) with permission to manage IAM identity providers and roles (
iam:CreateSAMLProvider,iam:CreateRole,iam:AttachRolePolicy). A SplitSecure identity provider, created in a threshold vault and approved by its Guardian Team. See Create an identity provider.
A second browser profile, signed in to the Web App, for the test sign-in. Start and finish the test in that same profile.
This guide makes an AWS account a connected app of your SplitSecure identity provider, so each console session in an IAM role starts only when your Guardian Team, the group of devices that together approve each proposal, approves it. You add SplitSecure as a SAML provider in IAM, create a role that trusts it, and register the account in the Web App.
Values you exchange
| Value | Where to find it | Where to paste it |
|---|---|---|
| SplitSecure metadata (XML) | The identity provider’s SAML endpoints card, Download metadata XML | AWS, Metadata document, in Add the SAML provider |
| AWS SAML metadata URL | AWS, the SAML provider you created, in Copy the AWS values | The Web App, AWS SAML Metadata URL, in Create the connected app |
| SAML provider ARN | AWS, IAM → Identity providers → your provider | The Web App, IAM Identity Provider ARN, in Create the connected app |
| Role ARN | AWS, IAM → Roles → your role | The Web App, Role ARN, in Create the connected app |
| Maximum session duration | AWS, IAM → Roles → your role → Maximum session duration | The Web App, Maximum session duration, in Create the connected app |
Add SplitSecure to AWS IAM
In the AWS Management Console
Open the Web App in another tab to download the metadata.
In the Web App, open Vaults, then your vault, then the identity provider. The SAML endpoints card shows three values:
- SAML IdP Entity ID
- SSO URL (HTTP-Redirect)
- SSO URL (HTTP-Post)
Under them, Download metadata XML saves the metadata file and Download Certificate offers the certificate in PEM format or DER format.
Click Download metadata XML on the card and save the file.
In the IAM console (opens in a new tab), choose Identity providers.
Click Add provider.
Fill in the fields.
Field Value Provider type SAML Provider name SplitSecureAny name; it ends the provider’s ARNMetadata document Upload the SplitSecure fileThe file from Download metadata XML Click Add provider.
Start the role from one of two places:
- On the new provider’s page, click Assign role.
- In the IAM navigation pane, choose Roles, then click Create role.
Fill in the trust settings.
Field Value Trusted entity type SAML 2.0 federation SAML 2.0-based provider The provider you created Access to be allowed Allow programmatic and AWS Management Console access Sign-in endpoint type Non-Regional endpoint Sign-in URLs to include unique identifiers With unique identifiersAWS gives the provider its own ID Click Next.
Select the permissions policies (opens in a new tab): Configure permissions in AWS for SAML federated principals for the federated users, for example ReadOnlyAccess.
Click Next.
Enter a role name, for example
SplitSecure-SAML-Role, and an optional description.Click Create role.
An existing role works too, if its trust policy names the SplitSecure provider.
The role’s Trust relationships tab shows a trust policy like this one. Click Edit trust policy to change its principals or conditions.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::<account-id>:saml-provider/SplitSecure"
},
"Action": "sts:AssumeRoleWithSAML",
"Condition": {
"StringEquals": {
"SAML:aud": "https://signin.aws.amazon.com/saml/acs/SAMLSPAA1AA1AA1111AA1A"
}
}
}
]
}To offer several permission levels, create one role per level. A connected app signs in to one role, so each role gets its own connected app in the Web App. A role can only trust a SAML provider in its own account. For a role in another account, add the provider there too, from the same metadata file, and register that account as a connected app of its own.
Connect AWS to SplitSecure
In the AWS Management Console
Go to IAM → Identity providers and open your provider.
Copy its ARN, for example
arn:aws:iam::111111111111:saml-provider/SplitSecure.Copy the provider’s SAML metadata URL. It has this shape, where
<ID>is the unique identifier AWS gave the provider:https://signin.aws.amazon.com/static/saml/<ID>/saml-metadata.xmlGo to IAM → Roles, open your role and copy its ARN, for example
arn:aws:iam::111111111111:role/SplitSecure-SAML-Role.On the role’s page, note its Maximum session duration.
The Web App accepts only a metadata URL of that exact shape. The generic https://signin.aws.amazon.com/static/saml-metadata.xml has no provider ID, and the Web App refuses it with “URL not allowed”.
In the Web App
In the Web App, open Vaults, then your vault, then the identity provider. Click New Connected App and pick the service provider’s card. Name is required, and the Threshold Identity Provider field is fixed to this provider.
- Click the AWS (SAML2) card.
- Enter a Name, for example
AWS production. - Keep NameID format on Transient. AWS receives a new identifier for each sign-in.
- In AWS SAML Metadata URL, paste the metadata URL.
- In IAM Identity Provider ARN, paste the provider’s ARN.
- In Role ARN, paste the role’s ARN.
- Under Session length, choose one, up to the role’s maximum session duration in IAM:
- Same for every sign-in, then enter the length.
- Chosen at each sign-in, then set Minimum, Maximum and Default.
- Optionally, under Session tags, click Add a session tag for each tag AWS should attach to the session, and pick where its value comes from:
- Fixed: the value you enter, on every sign-in.
- Chosen at each sign-in: from allowed values, or within a prefix and suffix.
- From the requester: their email address or session name.
Optionally, under Advanced Options, turn on Selective notifications so members can choose who gets notified for the Guardian Team’s proposals, set the Account Sensitivity banner shown on this connected app’s proposals (None, Low, Medium, High or Critical), and enter a Description or a Reason for creation.
Click Propose connected app. The Web App opens the proposal under Requests. The members of the Guardian Team approve it on their devices, in the mobile app. When the vote passes, the connected app appears under Connected Apps.
AWS refuses a sign-in that carries session tags unless the role’s trust policy also allows sts:TagSession for the SplitSecure provider. Add "sts:TagSession" next to "sts:AssumeRoleWithSAML" in the trust policy’s Action. To hold a tag to the values the connected app allows on the AWS side too, add a condition such as "StringEquals": { "aws:RequestTag/Env": ["dev", "prod"] }.
Test the sign-in
In the Web App
In the Web App, open Connected Apps, find the new connected app and click Log in. Some service providers, such as Iru, accept only a sign-in that starts on their side. For those, the Web App first sends you to the service provider, which sends you back. The Web App then shows the details of the connected app. If the page asks for a value, such as a NameID, enter it. To leave a note for the approvers, open Advanced Options and fill in Reason for access. Click Log in again. The members of the Guardian Team approve the sign-in on their devices, in the mobile app. When the vote passes, click Login on the proposal page to finish the sign-in at the service provider.
Only the browser profile that clicked Log in can show Login, and only once.
The access form has these fields.
| Field | Value |
|---|---|
| Session length | Within the connected app’s limits, its default preselectedShown only when the connected app lets the person signing in pick; the role and the account are fixed by the connected app |
| Session tags | Each tag the connected app lets the person signing in pickOne field per tag, holding a value the connected app allows |
Each sign-in carries a new NameID, the SAML subject, derived from the request’s proposal ID. AWS CloudTrail records it as the subject of the AssumeRoleWithSAML event, and the SplitSecure audit log shows the same ID on the request, with the requester. The session name is the requester’s email, adjusted to AWS’s session name rules (or the account’s id when it has no email).
On their devices, the Guardian Team members see the account, the role and the duration they approve.
The AWS Management Console opens, signed in to the connected app’s role. AWS asked for no password.
Troubleshooting
| Issue | Solution |
|---|---|
| The Web App refuses the metadata URL: “URL not allowed” | The URL is not the provider-specific oneUse https://signin.aws.amazon.com/static/saml/<ID>/saml-metadata.xml with your provider’s ID |
| The request is refused before any vote | The duration is outside the connected app’s limitsPick a duration in the range the sign-in page shows |
| AWS refuses the session after the vote | The duration exceeds the role’s maximum session duration in IAMAsk for a shorter duration, raise the role’s maximum in IAM, or create a connected app with a lower maximum |
| AWS reports an invalid response signature | The provider holds another identity provider’s metadataDownload the metadata again from the SAML endpoints card and update the IAM provider |
Not authorized to perform sts:AssumeRoleWithSAML | The role’s trust policy names another providerMake the trust policy’s Federated principal the exact ARN of your SAML provider |
| AWS reports an audience mismatch | SAML:aud is not the provider’s ACS URLCopy the full ACS URL from the provider’s page into the trust policy |
| The console opens in the wrong account | The connected app’s role belongs to another accountSign in through the connected app for that account |
| Access is denied after the sign-in | The role lacks permissionsAttach the permissions policies the users need |
| The session ends too early | The duration asked is short, or the connected app’s maximum is lowAsk for a longer duration, or create a connected app with a higher maximum and raise the role’s maximum in IAM |
External resources
- SAML 2.0 federation (opens in a new tab): IAM SAML federation setup
- Create a SAML identity provider in IAM (opens in a new tab): Creating IAM SAML identity providers
- Enable SAML 2.0 federated principals to access the console (opens in a new tab): Console access for SAML federated principals