Configure SAML assertions for the authentication response
After you have verified a user's identity in your organization, the external identity
provider (IdP) sends an authentication response to the AWS SAML endpoint at
https://. For a
list of potential region-code.signin.aws.amazon.com/samlregion-code replacements, see the
Region column in AWS Sign-In
endpoints. This response is a POST request that includes a SAML token that adheres to
the HTTP
POST Binding for SAML 2.0
When the IdP sends the response containing the claims to AWS, many of the incoming claims
map to AWS context keys. These context keys can be checked in IAM policies using the
Condition element. A listing of the available mappings follows in the section
Mapping SAML attributes to AWS trust policy context
keys.
Subject and NameID
The following excerpt shows an example. Substitute your own values for the marked ones.
There must be exactly one SubjectConfirmation element with a
SubjectConfirmationData element that includes both the
NotOnOrAfter attribute and a Recipient attribute. These attributes
include a value that must match the AWS endpoint
https://. For
a list of possible region-code.signin.aws.amazon.com/samlregion-code values, see the
Region column in AWS Sign-In
endpoints. For the AWS value, you can also use
https://signin.aws.amazon.com/static/saml, as shown in the following
example.
NameID elements can have the value persistent, transient, or consist of the
full Format URI as provided by the IdP solution. A value of persistent indicates that the
value in NameID is the same for a user between sessions. If the value is
transient, the user has a different NameID value for each session. Single sign-on
interactions support the following types of identifiers:
-
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent -
urn:oasis:names:tc:SAML:2.0:nameid-format:transient -
urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress -
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified -
urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName -
urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName -
urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos -
urn:oasis:names:tc:SAML:2.0:nameid-format:entity
<Subject> <NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">_cbb88bf52c2510eabe00c1642d4643f41430fe25e3</NameID> <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"> <SubjectConfirmationData NotOnOrAfter="2013-11-05T02:06:42.876Z" Recipient="https://signin.aws.amazon.com/saml"/> </SubjectConfirmation> </Subject>
Important
The saml:aud context key comes from the SAML recipient attribute because it is the SAML equivalent to the OIDC audience
field, for example, accounts.google.com:aud.
PrincipalTag SAML attribute
(Optional) You can use an Attribute element with the Name
attribute set to
https://aws.amazon.com/SAML/Attributes/PrincipalTag:.
This element allows you to pass attributes as session tags in the SAML assertion. For more
information about session tags, see Pass session tags in AWS STS.{TagKey}
To pass attributes as session tags, include the AttributeValue element that
specifies the value of the tag. For example, to pass the tag key-value pairs
Project = Marketing and CostCenter =
12345, use the following attribute. Include a separate Attribute
element for each tag.
<Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:Project"> <AttributeValue>Marketing</AttributeValue> </Attribute> <Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:CostCenter"> <AttributeValue>12345</AttributeValue> </Attribute>
To set the tags above as transitive, include another Attribute element with
the Name attribute set to
https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys. This is an optional
multivalued attribute that sets your session tags as transitive. Transitive tags persist when
you use the SAML session to assume another role in AWS. This is known as role chaining. For example, to set both the
Principal and CostCenter tags as transitive, use the following
attribute to specify the keys.
<Attribute Name="https://aws.amazon.com/SAML/Attributes/TransitiveTagKeys"> <AttributeValue>Project</AttributeValue> <AttributeValue>CostCenter</AttributeValue> </Attribute>
Role SAML attribute
You can use an Attribute element with the Name attribute set to
https://aws.amazon.com/SAML/Attributes/Role. This element contains one or more
AttributeValue elements that list the IAM identity provider and role to which
the user is mapped by your IdP. The IAM role and IAM identity provider are specified as a
comma-delimited pair of ARNs in the same format as the RoleArn and
PrincipalArn parameters that are passed to AssumeRoleWithSAML. This element must
contain at least one role-provider pair (AttributeValue element), and can contain
multiple pairs. If the element contains multiple pairs, then the user is asked to choose which
role to assume when they use WebSSO to sign in to the AWS Management Console.
Important
The value of the Name attribute in the Attribute tag is
case-sensitive. It must be set to https://aws.amazon.com/SAML/Attributes/Role
exactly.
<Attribute Name="https://aws.amazon.com/SAML/Attributes/Role"> <AttributeValue>arn:aws:iam::account-number:role/role-name1,arn:aws:iam::account-number:saml-provider/provider-name</AttributeValue> <AttributeValue>arn:aws:iam::account-number:role/role-name2,arn:aws:iam::account-number:saml-provider/provider-name</AttributeValue> <AttributeValue>arn:aws:iam::account-number:role/role-name3,arn:aws:iam::account-number:saml-provider/provider-name</AttributeValue> </Attribute>
RoleSessionName SAML
attribute
You can use an Attribute element with the Name attribute set to
https://aws.amazon.com/SAML/Attributes/RoleSessionName. This element contains one
AttributeValue element that provides an identifier for the temporary
credentials that are issued when the role is assumed. You can use this to associate the
temporary credentials with the user who is using your application. This element is used to
display user information in the AWS Management Console. The value in the AttributeValue
element must be between 2 and 64 characters long, can contain only alphanumeric characters,
underscores, and the following characters: . , + = @ -
(hyphen). It cannot contain spaces. The value is typically a user ID (johndoe) or
an email address (johndoe@example.com). It should not be a value that includes a
space, like a user's display name (John Doe).
Important
The value of the Name attribute in the Attribute tag is
case-sensitive. It must be set to
https://aws.amazon.com/SAML/Attributes/RoleSessionName exactly.
<Attribute Name="https://aws.amazon.com/SAML/Attributes/RoleSessionName"> <AttributeValue>user-id-name</AttributeValue> </Attribute>
SessionDuration SAML
attribute
(Optional) You can use an Attribute element with the Name
attribute set to https://aws.amazon.com/SAML/Attributes/SessionDuration". This element
contains one AttributeValue element that specifies how long the user can access
the AWS Management Console before having to request new temporary credentials. The value is an integer
representing the number of seconds for the session. The value can range from 900 seconds (15
minutes) to 43200 seconds (12 hours). If this attribute is not present, then the credential
last for one hour (the default value of the DurationSeconds parameter of the
AssumeRoleWithSAML API).
To use this attribute, you must configure the SAML provider to provide single sign-on
access to the AWS Management Console through the console sign-in web endpoint at
https://. For
a list of possible region-code.signin.aws.amazon.com/samlregion-code values, see the
Region column in AWS Sign-In
endpoints. You can optionally use the following URL:
https://signin.aws.amazon.com/static/saml. Note that this attribute extends
sessions only to the AWS Management Console. It cannot extend the lifetime of other credentials. However,
if it is present in an AssumeRoleWithSAML API call, it can be used to shorten the duration of the session. The default lifetime of the
credentials returned by the call is 60 minutes.
Note, too, that if a SessionNotOnOrAfter attribute is also defined, then the
lesser value of the two
attributes, SessionDuration or SessionNotOnOrAfter, establishes the
maximum duration of the console session.
When you enable console sessions with an extended duration the risk of compromise of the credentials rises. To help you mitigate this risk, you can immediately disable the active console sessions for any role by choosing Revoke Sessions on the Role Summary page in the IAM console. For more information, see Revoke IAM role temporary security credentials.
Important
The value of the Name attribute in the Attribute tag is
case-sensitive. It must be set to
https://aws.amazon.com/SAML/Attributes/SessionDuration exactly.
<Attribute Name="https://aws.amazon.com/SAML/Attributes/SessionDuration"> <AttributeValue>1800</AttributeValue> </Attribute>
SourceIdentity SAML attribute
(Optional) You can use an Attribute element with the Name
attribute set to https://aws.amazon.com/SAML/Attributes/SourceIdentity. This element
contains one AttributeValue element that provides an identifier for the person or
application that is using an IAM role. The value for source identity persists when you use
the SAML session to assume another role in AWS known as role chaining. The value for source identity is
present in the request for every action taken during the role session. The value that is set
cannot be changed during the role session. Administrators can then use AWS CloudTrail logs to
monitor and audit the source identity information to determine who performed actions with
shared roles.
The value in the AttributeValue element must be between 2 and 64 characters
long, can contain only alphanumeric characters, underscores, and the following characters:
. , + = @ - (hyphen). It cannot contain spaces. The value
is typically an attribute that is associated with the user such as a user id
(johndoe) or an email address (johndoe@example.com). It should not
be a value that includes a space, like a user's display name (John Doe). For more
information about using source identity, see Monitor and control actions
taken with assumed roles.
Important
If your SAML assertion is configured to use the SourceIdentity attribute, then your role trust policy must also
include the sts:SetSourceIdentity action, otherwise the assume role operation
will fail. For more information about using source identity, see Monitor and control actions
taken with assumed roles.
To pass a source identity attribute, include the AttributeValue element that
specifies the value of the source identity. For example, to pass the source identity
DiegoRamirez use the following attribute.
<Attribute Name="https://aws.amazon.com/SAML/Attributes/SourceIdentity"> <AttributeValue>DiegoRamirez</AttributeValue>
Mapping SAML attributes to AWS trust policy context keys
The tables in this section list commonly used SAML attributes and how they map to trust policy condition context keys in AWS. You can use these keys to control access to a role. To do that, compare the keys to the values that are included in the assertions that accompany a SAML access request.
Important
These keys are available only in IAM trust policies (policies that determine who can assume a role) and are not applicable to permissions policies.
In the eduPerson and eduOrg attributes table, values are typed either as strings or as
lists of strings. For string values, you can test these values in IAM trust policies using
StringEquals or StringLike conditions. For values that contain a
list of strings, you can use the ForAnyValue and ForAllValues
policy set
operators to test the values in trust policies.
Note
You should include only one claim per AWS context key. If you include more than one, only one claim will be mapped.
The following table shows eduPerson and eduOrg attributes.
eduPerson or eduOrg attribute (Name key) |
Maps to this AWS context key (FriendlyName key) |
Type |
|---|---|---|
|
|
|
List of strings |
|
|
|
List of strings |
|
|
|
String |
|
|
|
List of strings |
|
|
|
String |
|
|
|
String |
|
|
|
List of strings |
|
|
|
String |
|
|
|
List of strings |
|
|
|
List of strings |
|
|
|
List of strings |
|
|
|
List of strings |
|
|
|
List of strings |
|
|
|
List of strings |
|
|
|
List of strings |
|
|
|
List of strings |
|
|
|
List of strings |
The following table shows Active Directory attributes.
| AD attribute | Maps to this AWS context key | Type |
|---|---|---|
|
|
|
String |
|
|
|
String |
|
|
|
String |
|
|
|
String |
|
|
|
String |
|
|
|
String |
The following table shows X.500 attributes.
| X.500 attribute | Maps to this AWS context key | Type |
|---|---|---|
|
|
|
String |
|
|
|
String |
|
|
|
String |
|
|
|
String |
|
|
|
String |
|
|
|
String |
|
|
|
String |
