The IAM Roles Anywhere trust model
Amazon Identity and Access Management Roles Anywhere works by bridging the trust model of IAM and Public Key Infrastructure (PKI). The model connects the role, the IAM Roles Anywhere service principal, and identities encoded in X509 certificates, that are issued by a Certificate Authority (CA).
Role trusts
To use an IAM role with IAM Roles Anywhere, you must create a trust relationship with the IAM Roles Anywhere
service principal rolesanywhere.amazonaws.com
. To create the trust relationship, you
create a trust policy, a JSON policy document. The policy must grant the
permissions:
-
sts:AssumeRole
-
sts:SetSourceIdentity
-
sts:TagSession
Sessions issued by IAM Roles Anywhere have the source identity set to the common name(s) (CN) of the subject(s) you use in end-entity certificate(s) authenticating to the target role. IAM Roles Anywhere extracts values from the subject, issuer, and Subject Alternative Name (SAN) fields of the authenticating certificate and makes them available for policy evaluation via the sourceIdentity and principal tags. The sts:SourceIdentity key is present in the request when IAM Roles Anywhere initially sets the source identity while assuming a role. You can apply more authorization constraints by using condition clauses in the policy statement. The tags will also be evaluated against policies on any resources accessed with the issued session.
Additionally, sessions issued by Amazon have a Session Name property that is used as part of the assumed role ARN. IAM Roles Anywhere sets this automatically, using the hex-encoded serial number of the authenticating certificate.
To examine the contents of a certificate, use the following command:
$
openssl x509 -text -noout -in certificate.pem
Certificate: Data: Version: 3 (0x2) Serial Number: 1f:71:c5:11:4a:11:9f:c0:cc:5a:5a:52:fb:37:20:ad Signature Algorithm: sha256WithRSAEncryption Issuer: C=US, O=Amazon, OU=IAM, ST=Washington, CN=Roles Anywhere, L=Seattle Validity Not Before: Apr 20 14:13:43 2022 GMT Not After : Jan 10 15:13:43 2023 GMT Subject: CN=awsUser # remainder omitted...
In this case, the value awsUser
becomes the source identity. The values from the
Issuer
field become principal tags in the resulting session.
For more information, see:
Signature validation
To authenticate a request for credentials, IAM Roles Anywhere validates the incoming signature by using the signature validation algorithm required by the key type of the certificate, for example RSA or ECDSA. After validating the signature, IAM Roles Anywhere checks that the certificate was issued by a certificate authority configured as a trust anchor in the account using algorithms defined by public key infrastructure X.509 (PKIX) standards.
End entity certificates must satisfy the following constraints to be used for authentication:
The certificates MUST be X.509v3.
If the
CA
field is present in the basic constraints extension, its value MUST befalse
.The key usage MUST include
Digital Signature
.The signing algorithm MUST include
SHA256
or stronger.MD5
andSHA1
signing algorithms are rejected.
Certificates used as trust anchors must satisfy the same requirements for signature algorithm, but with the following differences:
The key usage MUST include
Certificate Sign
, and MAY includeCRL Sign
. Certificate Revocation Lists (CRLs) are an optional feature of IAM Roles Anywhere.Basic constraints MUST include
CA: true
.
Trust policy
Temporary credentials for IAM roles are issued to IAM Roles Anywhere clients via the API method
CreateSession
. In order for the call to be authorized, the target role of the
CreateSession
API call must have an Assume Role Policy Document to trust the IAM Roles Anywhere
service principal.
Important
It is also recommended to have additional condition statements to further restrict authorization based on attributes that are extracted from the X.509 certificate.
The Subject
, Issuer
, and Subject Alternative Name (SAN)
fields from X509 certificates are extracted and used
as PrincipalTag
elements in the session.
Note
These tags are also available to be used in conditions in the identity-based policy attached to the role.
Certificate Subject fields mapping
IAM Roles Anywhere maps Relative Distinguished Names (RDNs) from an
authenticating certificate's Subject into distinct PrincipalTag
elements in the session.
The following example shows a trust policy that adds a condition based on the
Subject Common Name (CN)
of the certificate. For example, if the identity
asserted in the certificate is Alice
, a condition can be created on the
CN
of the Subject.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rolesanywhere.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession", "sts:SetSourceIdentity" ], "Condition": { "StringEquals": { "aws:PrincipalTag/x509Subject/CN": "Alice" }, "ArnEquals": { "aws:SourceArn": [ "arn:aws:rolesanywhere:
region
:account
:trust-anchor/TA_ID
" ] } } } ] }
Certificate Issuer fields mapping
IAM Roles Anywhere maps RDNs from an authenticating certificate’s Issuer into distinct PrincipalTag
elements in the session.
The following example shows a trust policy that adds a condition based on the
Issuer Common Name (CN)
of the certificate. For example, if the issuer identity
asserted in the certificate is Bob
, a condition can be created on the
CN
of the Issuer.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rolesanywhere.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession", "sts:SetSourceIdentity" ], "Condition": { "StringEquals": { "aws:PrincipalTag/x509Issuer/CN": "Bob" }, "ArnEquals": { "aws:SourceArn": [ "arn:aws:rolesanywhere:
region
:account
:trust-anchor/TA_ID
" ] } } } ] }
Certificate Subject Alternative Name (SAN) fields mapping
X509v3 certificates may include an extension to define additional
identities, call Subject Alternative Names (SANs). The SAN can have
multiple values, each of which can be one of nine types - Domain Name System
(DNS) names, Uniform Resource Indicators (URIs), Directory Names, IP
addresses, "Other" names, EDI party names, X400 addresses, RFC 822 names, or
registered OIDs. IAM Roles Anywhere will map the first value of the following types: DNS
Names
, Directory Name (DN)
, and URI Names
.
The resulting tags will be prefixed with x509SAN, with a corresponding type
code. The type code will be one of DNS, URI, or Name. For values of type DN,
the individual RDNs will be parsed, as with Subject and Issuer.
Certificate: Data: Version: 3 (0x2) Serial Number: 1f:71:c5:11:4a:11:9f:c0:cc:5a:5a:52:fb:37:20:ad Signature Algorithm: sha256WithRSAEncryption Issuer: C=US, O=Amazon, OU=IAM, ST=Washington, CN=RolesAnywhere, L=Seattle Validity Not Before: Apr 20 14:13:43 2022 GMT Not After : Jan 10 15:13:43 2023 GMT Subject: CN=Alice X509v3 extensions: X509v3 Subject Alternative Name: DNS:example.com, URI:spiffe://example.com/workload/alice, DirName:/CN=Alice # remainder omitted...
The complete set of session principal tags, including the SAN fields, will look like the following:
"aws:PrincipalTag/x509Subject/CN": "Alice" "aws:PrincipalTag/x509Issuer/C": "US" "aws:PrincipalTag/x509Issuer/O": "Amazon" "aws:PrincipalTag/x509Issuer/OU": "IAM" "aws:PrincipalTag/x509Issuer/ST": "Washington" "aws:PrincipalTag/x509Issuer/L": "Seattle" "aws:PrincipalTag/x509Issuer/CN": RolesAnywhere "aws:PrincipalTag/x509SAN/DNS": "example.com" "aws:PrincipalTag/x509SAN/URI": "spiffe://example.com/workload/alice" "aws:PrincipalTag/x509SAN/Name/CN": "Alice"
The following example shows a trust policy that adds a condition based on the
SAN
fields of the certificate.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rolesanywhere.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession", "sts:SetSourceIdentity" ], "Condition": { "StringEquals": { "aws:PrincipalTag/x509SAN/DNS": "example.com", "aws:PrincipalTag/x509SAN/URI": "spiffe://example.com/workload/alice", "aws:PrincipalTag/x509SAN/Name/CN": "Alice" }, "ArnEquals": { "aws:SourceArn": [ "arn:aws:rolesanywhere:
region
:account
:trust-anchor/TA_ID
" ] } } } ] }
Note
RFC 5280
Using the aws:SourceArn
or aws:SourceAccount
or sts:SourceIdentity
condition keys
In general, it is strongly recommended that you use the
aws:SourceArn
or the
aws:SourceAccount
global condition keys or the
sts:SourceIdentity
condition key in your role trust policies. This combination of conditions implements least privilege permissions and prevents IAM Roles Anywhere
from acting as a potential confused deputy. When a client
obtains temporary security credentials from IAM Roles Anywhere, the aws:SourceArn
and aws:SourceAccount
will be set
based on the ARN of the trust anchor specified in the call to CreateSession
.
To use the aws:SourceArn
and aws:SourceAccount
global condition keys,
set the value to the Amazon Resource Name (ARN) or account of the trust anchor that you expect to use
for authentication. As an example, consider the following role trust policy.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rolesanywhere.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession", "sts:SetSourceIdentity" ], "Condition": { "ArnEquals": { "aws:SourceArn": [ "arn:aws:rolesanywhere:
region
:account
:trust-anchor/TA_ID
" ] } } } ] }
To use the sts:SourceIdentity
condition key,
set the source identity prefix and source identity value according
to the following rules.
As an example, consider the following role trust policy.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rolesanywhere.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:SetSourceIdentity" ], "Condition": { "StringEquals": { "sts:SourceIdentity": [ "
${sourceIdentityPrefix}${sourceIdentityValue}
" ] }, "ArnEquals": { "aws:SourceArn": [ "arn:aws:rolesanywhere:region
:account
:trust-anchor/TA_ID
" ] } } }, { "Effect": "Allow", "Principal": { "Service": "rolesanywhere.amazonaws.com" }, "Action": [ "sts:TagSession" ] } ] }
Source identity rules
We define a source identity prefix as follows:
"CN="
: the common name of the subject in the certificate is set and less than or equal to the length threshold."ID="
: the common name of the subject in the certificate is NOT set.""
: (empty string) the common name of the subject in the certificate is set and greater than the length threshold but less than 64 characters.
The value following a source identity prefix is as follows:
"CN="
: the common name of the subject in the certificate."ID="
: the hex-encoded certificate serial number.""
: the common name of the subject in the certificate.
The length threshold is 61 characters.
Revocation
Certificate revocation is supported through the use of imported certificate revocation lists (CRLs).
Currently, certification revocation is only supported by the API and CLI.
You can import a CRL that is generated from your CA using ImportCrl
API or
import-crl
CLI command. Certificates
used for authentication will be checked for their revocation status.
Callbacks to CRL Distribution Points (CDPs) or Online Certificate Status Protocol (OCSP) endpoints are not supported.