# The IAM Roles Anywhere trust model IAM Roles Anywhere trust model AWS 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 X.509 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_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 AWS 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: + [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) + [IAM roles terms and concepts: trust policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#term_trust-policy) + [Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) + [Things to know about source identity](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_control-access_monitor.html#id_credentials_temp_control-access_monitor-know) + [Passing session tags in AWS Security Token Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) ## 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 be `false`. + The key usage MUST include `Digital Signature`. + The signing algorithm MUST include `SHA256` or stronger. `MD5` and `SHA1` 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 include `CRL Sign`. Certificate Revocation Lists (CRLs) are an optional feature of IAM Roles Anywhere. + Basic constraints MUST include `CA: true`. **Important** For AWS Private CA trust anchors, only the validity period can be modified after creation. When the validity period changes, you must call UpdateTrustAnchor to register this change. IAM Roles Anywhere honors certificates based on the validity period found during the most recent TrustAnchor Create/Update event. ## Trust policy Temporary credentials for IAM roles are issued to IAM Roles Anywhere clients via the API method `CreateSession`. 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 (`rolesanywhere.amazonaws.com`). **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. When you use X.509 certificates, IAM Roles Anywhere extracts the following fields and makes them available as `PrincipalTag` elements in the session: + `Subject` + `Issuer` + `Subject Alternative Name (SAN)` These values need to match the pattern defined in [STS session tags](https://docs.aws.amazon.com/STS/latest/APIReference/API_Tag.html). The service ignores values that do not match this pattern. You cannot use these values in policy conditions. **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. ------ #### [ JSON ] **** ``` { "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:us-east-1:123456789012: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. ------ #### [ JSON ] **** ``` { "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:us-east-1:123456789012:trust-anchor/TA_ID" ] } } } ] } ``` ------ **Certificate Subject Alternative Name (SAN) fields mapping** X.509v3 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... ``` For the above certificate, the session principal tags and 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" // Additional principal tags may be available... ``` Some X.509 certificate fields can contain multiple values. For example, a Subject can have multiple Organization Unit (OU) values in the certificate. Because principal tags do not support multiple values, IAM Roles Anywhere combines multiple values into a single string, separating them with forward slashes (/) in the order they appear in the certificate. For example, consider a certificate with these Subject values: ``` CN=alice, OU=Security, OU=Engineering, OU=Research ``` IAM Roles Anywhere creates the following principal tag: ``` "aws:PrincipalTag/x509Subject/OU": "Security/Engineering/Research" ``` This same behavior applies to any certificate field that contains multiple values. The order of values in the principal tag matches their order in the certificate. The following example shows a trust policy that adds a condition based on the `SAN` fields of the certificate. ------ #### [ JSON ] **** ``` { "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:us-east-1:123456789012:trust-anchor/TA_ID" ] } } } ] } ``` ------ **Note** [RFC 5280](https://datatracker.ietf.org/doc/html/rfc5280) allows certificates with empty subjects if and only if the SAN extension is present and marked critical. Certificates with empty subjects are NOT yet supported, since IAM Roles Anywhere uses the certificate subject as the key of the Subject resource to visualize and audit activities for certificates that are authenticated with IAM Roles Anywhere. For more information about Subject resource, see [Monitoring with IAM Roles Anywhere subjects](monitoring-subjects.md). **Using the `aws:SourceArn` or `aws:SourceAccount` or `sts:SourceIdentity` condition keys** In general, it is strongly recommended that you use the [aws:SourceArn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) or the [aws:SourceAccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) global condition keys or the [sts:SourceIdentity](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_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](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html). 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. ------ #### [ JSON ] **** ``` { "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:us-east-1:123456789012:trust-anchor/TA_ID" ] }, "StringEquals": { "aws:PrincipalTag/x509Issuer/CN": "YourCN" } } } ] } ``` ------ To use the `sts:SourceIdentity` condition key, set the source identity prefix and source identity value according to the following [rules](#source-identity-rules). As an example, consider the following role trust policy. ------ #### [ JSON ] **** ``` { "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:us-east-1:123456789012:trust-anchor/TA_ID" ] } } }, { "Effect": "Allow", "Principal": { "Service": "rolesanywhere.amazonaws.com" }, "Action": [ "sts:TagSession" ], "Condition": { "StringEquals": { "aws:PrincipalTag/x509Issuer/CN": "YourCN" } } } ] } ``` ------ # Certificate attribute mapping IAM Roles Anywhere provides you with the capability to define a custom set of mapping rules, enabling you to specify which data are extracted from authenticating certificates as session tags for authorization policies. These customized attribute mappings are associated with a [profile](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-rolesanywhere-profile.html). Attributes are data elements that come from specific fields in the certificate. You can use specifiers to represent one or more attributes. **Note** For information about session tag quotas, see [Session tagging operations](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html#id_session-tags_operations). **Topics** + [ ## Default mapping behavior ](#attribute-mapping-default) + [ # Put attribute mappings ](put-attribute-mapping.md) + [ # Delete attribute mappings ](delete-attribute-mappings.md) + [ # Attribute mapping and trust policy ](attribute-mapping-and-trust-policy.md) ## Default mapping behavior The following attributes are mapped by default when you create a profile. The default mapping rules are as follows: + `x509Subject`: maps all supported Relative Distinguished Names (RDNs) from an authenticating certificate's Subject into distinct `PrincipalTag` elements in the session. + `x509Issuer`: maps all supported Relative Distinguished Names (RDNs) from an authenticating certificate's Issuer into distinct `PrincipalTag` elements in the session. + `x509SAN (Subject Alternative Name)`: maps the ** first** value of the following types: `DNS Names`, `Directory Name (DN)`, and `URI Names` To view your current mappings associated with a profile, using the following command: ``` $ aws rolesanywhere get-profile --profile-id PROFILE_ID ``` Default mapping rules in a JSON format: ``` "attributeMappings": [ { "mappingRules": [ { "specifier": "*" } ], "certificateField": "x509Issuer" }, { "mappingRules": [ { "specifier": "DNS" }, { "specifier": "URI" }, { "specifier": "Name/*" } ], "certificateField": "x509SAN" }, { "mappingRules": [ { "specifier": "*" } ], "certificateField": "x509Subject" } ] ``` **Note** If you see `*` as a specifier, it signifies the default behavior, which maps all recognizable RDNs for `x509Subject`, `x509Issuer` and `x509SAN/Name`. However, `*` does not have a defined behavior in the context of `x509SAN/URI`, `x509SAN/DNS`, or `x509SAN/`. The specifier `Name/` represents the first recognizable attribute of the `Directory Name`. Both `Name` and `Name/` are equivalent to `Name/*` and will be displayed as `Name/*`in the mapping rule. # Put attribute mappings ## Put attribute mappings (command line interface) `put-attribute-mapping` enables you to attach new mapping rules to your profile. When using that profile, the certificate mapping behavior changes according to your customized rules. To put a mapping rule, using the following command: ``` $aws rolesanywhere put-attribute-mapping \ --certificate-field CERTIFICATE_FIELD \ --mapping-rules specifier=SPECIFIER \ --profile-id PROFILE_ID ``` The `CERTIFICATE_FIELD` can be in one of `x509Subject`, `x509Issuer` and `x509SAN`. The `SPECIFIER` is a string enforced by a standard (for example, OID) that can map to a piece of information encoded in the certificate. For example, to add mapping rules for `x509Subject/CN` and `x509Subject/OU`, use the following command: ``` $aws rolesanywhere put-attribute-mapping \ --certificate-field x509Subject \ --mapping-rules specifier=CN specifier=OU \ --profile-id PROFILE_ID ``` ## Put attribute mappings (console) 1. Sign in to [IAM Roles Anywhere console](https://console.aws.amazon.com/rolesanywhere/home). 1. Scroll to find profile table and **choose the profile** to add certificate attribute mappings. 1. Within profile detail page scroll towards **Certificate attribute mappings** section and choose **Manage mappings**. 1. Scroll to find the **Add mappings** button and click on it. 1. Choose a certificate field from either `Subject`, `Issuer`, or `Subject Alternative Name` in the dropdown list, and enter the specifier 1. Select **Save changes** to add attribute mappings. # Delete attribute mappings ## Delete attribute mappings (command line interface) `delete-attribute-mapping` enables you to delete mapping rules from your profile. When using that profile, the attribute specified by the deleted mapping rule will not be mapped from a certificate. To delete a mapping rule, using the following command: ``` $aws rolesanywhere delete-attribute-mapping \ --certificate-field CERTIFICATE_FIELD \ --specifiers SPECIFIERS \ --profile-id PROFILE_ID ``` The `CERTIFICATE_FIELD` can be in one of `x509Subject`, `x509Issuer` and `x509SAN`. The `SPECIFIER` is a string enforced by a standard (for example, OID) that exists in your current mapping rules. For example, to delete mapping rules for `x509Subject/CN` and `x509Subject/OU`, use the following command: ``` $aws rolesanywhere delete-attribute-mapping \ --certificate-field x509Subject \ --specifiers CN OU \ --profile-id PROFILE_ID ``` ## Delete attribute mappings (console) 1. Sign in to [IAM Roles Anywhere console](https://console.aws.amazon.com/rolesanywhere/home). 1. Scroll to find profile table and **choose the profile** to remove certificate attribute mappings. 1. Within profile detail page scroll towards **Certificate attribute mappings** section and choose **Manage mappings**. 1. Scroll to find the corresponding attribute mapping row and click on **Remove mapping** button associated with it. 1. Select **Save changes** to remove attribute mappings. # Attribute mapping and trust policy It is recommended to have condition statements in the Assume Role Policy Document to restrict authorization based on attributes that are extracted from an end-entity X.509 certificate. For more information about the role trust policy, see [Trust policy](trust-model.md#trust-policy). The attribute mapping field of a profile controls which attributes from an authenticating X.509 certificate will be mapped for principal tags. Therefore, while adding condition statements to an Assume Role Policy Document, be cautious that the specifiers used in mapping rules for authorization need to be mapped accordingly. The following example shows trust policies that add a condition based on the `Issuer Common Name (CN)` of the certificate. ------ #### [ JSON ] **** ``` { "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:us-east-1:123456789012:trust-anchor/TA_ID" ] } } } ] } ``` ------ If a profile is used with an Attribute Mapping field that lacks `specifier: CN` or `specifier: *` in the mappingRules for `x509Issuer`, the first condition in the Assume Role Policy Document will evaluate as `false` because there will be no value mapped `aws:PrincipalTag/x509Issuer/CN`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "rolesanywhere.amazonaws.com" }, "Action": [ "sts:AssumeRole", "sts:TagSession", "sts:SetSourceIdentity" ], "Condition": { "StringNotEquals": { "aws:PrincipalTag/x509Issuer/CN": "Bob" }, "ArnEquals": { "aws:SourceArn": [ "arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/TA_ID" ] } } } ] } ``` ------ Likewise, if the condition is `StringNotEquals`, the condition will evaluate to `true` using the same profile. This happens because the condition is disregarded when the principal tag is dropped due to attribute mapping APIs. Having the Attribute Mapping field provided below in a profile, the `StringEquals` condition for `x509Issuer/CN` will assess to `false`, or the `StringNotEquals` condition will assess to `true`. ``` "attributeMappings": [ { "mappingRules": [ { "specifier": "O" } ], "certificateField": "x509Issuer" }, { "mappingRules": [ { "specifier": "DNS" }, { "specifier": "URI" }, { "specifier": "Name/*" } ], "certificateField": "x509SAN" }, { "mappingRules": [ { "specifier": "*" } ], "certificateField": "x509Subject" } ] ``` ## 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 61 characters. + `"ID="`: the common name of the subject in the certificate is not set. This value is left-padded with zero to be even in length. + `""`: (empty string) the common name of the subject in the certificate is set and has a length from 62 to 64 characters. Hex encoding example: + Decimal serial number 291 converts to hex 123, which becomes `ID=0123` + Decimal serial number 17767 converts to hex 4567, which becomes `ID=4567` ## 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 [https://docs.aws.amazon.com/rolesanywhere/latest/APIReference/API_ImportCrl.html](https://docs.aws.amazon.com/rolesanywhere/latest/APIReference/API_ImportCrl.html) API or [https://docs.aws.amazon.com/cli/latest/reference/rolesanywhere/import-crl.html](https://docs.aws.amazon.com/cli/latest/reference/rolesanywhere/import-crl.html) 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.