AWS rolesanywhere documentation change
Summary
Clarified trust policy requirements, expanded X.509 field handling details, added examples for multi-value certificate fields, and specified source identity formatting rules with hex encoding examples.
Security assessment
The changes provide detailed documentation about security controls (certificate field validation, principal tag patterns, source identity formatting) but do not indicate a specific security vulnerability being addressed. The updates improve clarity for secure configuration without evidence of patching a known exploit.
Diff
diff --git a/rolesanywhere/latest/userguide/trust-model.md b/rolesanywhere/latest/userguide/trust-model.md index 0e32325bd..7ca145d07 100644 --- a//rolesanywhere/latest/userguide/trust-model.md +++ b//rolesanywhere/latest/userguide/trust-model.md @@ -92 +92 @@ Certificates used as trust anchors must satisfy the same requirements for signat -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. +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`). @@ -98 +98,12 @@ It is also recommended to have additional condition statements to further restri -The `Subject`, `Issuer`, and `Subject Alternative Name (SAN)` fields from X509 certificates are extracted and used as `PrincipalTag` elements in the session. +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. @@ -195 +206 @@ X509v3 certificates may include an extension to define additional identities, ca -The complete set of session principal tags, including the SAN fields, will look like the following: +For the above certificate, the session principal tags and the SAN fields will look like the following: @@ -198,9 +209,9 @@ The complete set of session principal tags, including the SAN fields, will look - "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/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", @@ -207,0 +219,4 @@ The complete set of session principal tags, including the SAN fields, will look + // 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. @@ -208,0 +224,11 @@ The complete set of session principal tags, including the SAN fields, will look +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. @@ -322 +348 @@ 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. + * `"CN="`: the common name of the subject in the certificate is set and less than or equal to 61 characters. @@ -324 +350 @@ We define a source identity prefix as follows: - * `"ID="`: the common name of the subject in the certificate is NOT set. + * `"ID="`: the common name of the subject in the certificate is not set. @@ -326 +352 @@ We define a source identity prefix as follows: - * `""`: (empty string) the common name of the subject in the certificate is set and greater than the length threshold but less than 64 characters. + * `""`: (empty string) the common name of the subject in the certificate is set and has a length from 62 to 64 characters. @@ -335 +361 @@ The value following a source identity prefix is as follows: - * `"ID="`: the hex-encoded certificate serial number. + * `"ID="`: the hex-encoded certificate serial number. This value is left-padded with zero to be even in length. @@ -342 +368,8 @@ The value following a source identity prefix is as follows: -The length threshold is 61 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` + + +