Business Challenge
The problem Roles Anywhere solves is real and worth solving. “Using IAM Roles Anywhere means you don't need to manage long-term AWS credentials for workloads running outside of AWS.” A build agent, an on-premises job server, a VM in another cloud — instead of an access key pair that lives until somebody remembers it, the workload presents an X.509 certificate and receives a temporary session.
The mechanism is a trust anchor: “A trust anchor is a reference to either AWS Private CA or an external CA certificate… There can be several trust anchors in one AWS account.”
Register the CA, point a role at the service, and you are done. The word "anchor" does a lot of work in that sentence, and it is the wrong word for what the object does.
AWS puts this under a heading called Account trust boundary, and the heading is the answer: “For IAM Roles Anywhere, the trust boundary is established at the account level.”
What that means in practice: “Certificates issued by any trust anchor in the account can be used to assume any target role in that same account, unless you specify conditions in the role's trust policy.”
So two teams, two CAs, two trust anchors, two roles in one account is not two isolated paths. It is four, and the two you did not intend are indistinguishable from the two you did. Registering a CA for one purpose grants it the union of everything Roles Anywhere can reach in that account.
FixEvery Roles Anywhere role's trust policy restricts authorization somehow. Where the requirement is to bind a role to one specific anchor, that condition is aws:SourceArn carrying its ARN.
The second bullet under that heading is one sentence and it is the one worth carrying away: “There is no automatic integration with organization-wide controls.”
An organisation that governs identity centrally — and today's daily is about exactly that machinery — does not get Roles Anywhere governance for free. The trust decision lives in the account, in a role's trust policy, written by whoever created the role.
That is a governance surface in the one place org-level tooling does not look, and it is created by a team solving a credential-hygiene problem, usually quickly, usually with the console's default.
FixTreat rolesanywhere:CreateTrustAnchor as a privileged action and deny it outside a reviewed path.
Revocation exists, and it is pull-only:
“Certificate revocation is supported through the use of imported certificate
revocation lists (CRLs)… You can import a CRL that is generated from your CA using
ImportCrl…”
And then the sentence that decides your incident response: “Callbacks to CRL Distribution Points (CDPs) or Online Certificate Status Protocol (OCSP) endpoints are not supported.”
AWS never asks your PKI whether a certificate is still good. It knows only what you last imported. So
a certificate revoked in your CA keeps working until somebody runs
ImportCrl — and the gap between those two events is not visible from
either side.
Make CRL import part of the revocation procedure itself, not a scheduled job that runs afterwards.
Architecture
The exchange is: certificate → CreateSession → temporary
credentials, with the role's trust policy as the only gate.
What the trust policy has to say
Three actions, not one:
“The policy must grant the permissions: sts:AssumeRole,
sts:SetSourceIdentity, sts:TagSession.”
The second and third are what make the certificate's contents available as policy inputs, which is the part worth understanding: “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.”
So a trust policy can condition on aws:PrincipalTag/x509Subject/CN,
aws:PrincipalTag/x509Issuer/CN,
aws:PrincipalTag/x509SAN/DNS and the rest. That is a genuinely good design
— your PKI's naming becomes your authorisation vocabulary, and it composes with everything
#37 covers about trust policies generally.
The restricting condition is separate, and AWS names three of them rather than one:
“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.”
aws:SourceArn is the right one when the requirement is specifically to bind a
role to a particular anchor, because that is what it carries:
“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.” It is not the only condition that can restrict the
path, though — a policy keyed on sts:SourceIdentity or on the
x509Issuer tags restricts it too, and AWS's own examples pair an issuer
condition with the source ARN rather than relying on either alone.
Four places the certificate's identity changes shape
This is the half that will cost someone an afternoon, because in each case the certificate is valid, the session is issued, and a condition that reads correctly does not fire.
The source identity prefix depends on the length of the common name. Three rules:
“"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… "" (empty string): the common name of the subject in the
certificate is set and has a length from 62 to 256 characters.”
A condition written as StringEquals sts:SourceIdentity "CN=buildagent-..."
works for every certificate until one is issued with a 62-character CN, at which point the prefix is gone
and the condition fails. Past 256 the call does not degrade, it stops:
“IAM Roles Anywhere does not support subject common names longer than 256 characters, and the
CreateSession request fails.”
Only the first SAN value of each type is mapped.
“IAM Roles Anywhere will map the first value of the following types:
DNS Names, Directory Name (DN), and
URI Names.” A certificate carrying two DNS SANs exposes one. A
condition on the second never matches, and the certificate contains it.
Repeated RDNs are flattened into one string, in certificate order.
“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.” So CN=alice, OU=Security, OU=Engineering, OU=Research
becomes one tag with the value Security/Engineering/Research.
An equality condition on that tag is an assertion about the order your CA happens to emit OUs in. Reissue with the same three OUs in a different order and the policy stops matching.
The session name defaults to the serial number, and overriding it is opt-in on the profile. The default is unambiguous: “The default role session name, when not provided, is the serial number of the X.509 certificate provided in a session request.” So out of the box the assumed-role ARN in CloudTrail identifies the certificate rather than the workload, and the readable identity lives in source identity instead.
It can be changed, and the control sits on the profile rather than the request:
“The acceptRoleSessionName option on a profile controls whether or
not a role session name will be accepted in a session request with this profile.” Set it and
“the default role session name, which is the serial number of the X.509 certificate, will no
longer be used and included in the ARN or ID of the assumed role user.”
Two defaults worth knowing before you rely on either.
“By default, the acceptRoleSessionName attached to the profile is
false. If you provide a custom role session name in the
CreateSession request but custom role session names are not accepted, you will
receive an Access Denied error.” A client that starts sending
roleSessionName against an unprepared profile does not fall back to the
serial — it fails, and it fails looking like a permissions problem.
And the reverse is not symmetric:
“when a CreateSession request does not include a role session name,
the role session name defaults to the serial number of the end-entity X.509 certificate used to
authenticate the request, even when the acceptRoleSessionName on the
profile is true.” Enabling the option permits custom
names; it does not guarantee them. So a CloudTrail query written on the assumption that every session
carries a readable name will still meet serial numbers from any client that omitted one.
Where the serial does appear, AWS's worked conversions show the encoding —
“Decimal serial number 291 converts to hex 123, which becomes
ID=0123… Decimal serial number 17767 converts to hex 4567, which
becomes ID=4567” — and note that the older
sessionName request parameter is “no longer used. Instead, use the
roleSessionName parameter.”
The trust policy section says the extracted values “need to match the pattern defined in STS session tags. The service ignores values that do not match this pattern. You cannot use these values in policy conditions.” Read in isolation that last sentence appears to forbid the very thing every example on the page does. It does not: its subject is the ignored values — the ones that failed the session-tag pattern. The tags that do match are usable, which is why the page then says they are “also available to be used in conditions in the identity-based policy attached to the role” and shows five policies conditioning on them. Worth knowing because the practical consequence is real: a certificate field containing characters the session-tag pattern rejects is dropped silently, and a condition on it fails closed with nothing to show you why.
Why This Architecture Holds Up
The certificate requirements are strict, and that is load-bearing
For end-entity certificates:
“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.”
The CA: false requirement is the interesting one — it stops an
intermediate CA certificate being used as a workload identity, which would otherwise let anything that
could issue certificates also authenticate as one.
“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.” So the validity AWS enforces is the one it read when you last created or updated the anchor. Change it in Private CA and nothing takes effect until UpdateTrustAnchor runs. This is the same shape as the CRL behaviour: Roles Anywhere holds a copy of your PKI's state and does not refresh it on its own.
The profile is the second gate, and it has one slot
“A profile can have many IAM roles, but only one session policy. Any session
returned by a CreateSession call that references the profile will have its
permissions limited by the session policy.”
That shapes how you lay profiles out: a profile is the unit of session-policy granularity, so roles whose sessions need different ceilings belong in different profiles regardless of how convenient one profile would be. And a session policy only subtracts — it is the seventh gate from #35, in a place you may not have expected to find it.
Session length is negotiated between three places, and the lowest wins
The request parameter has a wide range and is optional: “The duration, in seconds, of the role session. The value is optional and can range from 900 seconds (15 minutes) up to 43200 seconds (12 hours).” So 15 minutes is the floor the API will accept, not what a session is.
What you actually get is documented as arithmetic:
“finalDurationSeconds = min(profileDurationSeconds,
createSessionDurationSeconds)… If createSessionDurationSeconds
isn't provided, then finalDurationSeconds =
profileDurationSeconds.”
And there is a third ceiling that fails loudly rather than clamping:
“Note that if finalDurationSeconds is greater than the maximum
session duration (MaxSessionDuration) set on the role, you will receive an
error response from the API.”
That last one is worth reading twice, because the other two combine by taking a minimum and this one does
not. Raise a profile's duration above the role's MaxSessionDuration and
sessions stop being issued at all — the request errors instead of quietly getting the shorter
window. Profile duration and role MaxSessionDuration are set by different
people, usually at different times.
The relationship underneath explains why all of this looks like STS, because it is: “CreateSession is an X.509 wrapper around AssumeRole. The temporary session credentials are delivered to RolesAnywhere by AssumeRole, and then passed on without modification in the result of CreateSession.”
One operational detail that comes with that wrapper and is easy to miss:
“CloudTrail events for successfully authenticated CreateSession
requests also include an additionalEventData object. This object records
signing characteristics that IAM Roles Anywhere detected while authenticating the request.”
Examples AWS gives include required signing headers not covered by the signature, and a mismatch between
the declared signing algorithm and the certificate key type — so there is a place to check whether
your fleet's clients are signing correctly, before a change in the signing process makes it urgent.
Everything is Regional, including the pairing
“All IAM Roles Anywhere resources are regional and they must be created in the same account and region to be used together.” A trust anchor and a profile in different Regions are not a configuration, and the multi-Region story is replication of the whole set rather than one anchor serving many Regions.
That cuts both ways and the good side is worth naming: because the account is the trust boundary and resources are Regional, a per-workload account remains the cleanest isolation available. The documented multi-account guidance is an onward pointer rather than a feature, which is itself informative — there is no org-level construct here to reach for.
Key Architecture Decisions
| Decision | Choice | Reasoning |
|---|---|---|
| Restricting the trust path | A condition, always — aws:SourceArn, aws:SourceAccount or sts:SourceIdentity |
With no condition at all, any trust anchor in the account can assume the role. |
| Binding a role to one specific CA | aws:SourceArn carrying that trust anchor's ARN |
It is set from the anchor named in the CreateSession call, so it is the key that expresses this. |
| Session length | Set it on the profile; keep the role's MaxSessionDuration above it |
Profile and request combine by minimum, but exceeding MaxSessionDuration errors rather than clamping. |
| Readable session names | acceptRoleSessionName on the profile, and a client that always sends one |
It defaults to false; and even when true, a request omitting the name still gets the serial. |
| Isolating two workloads | Separate accounts, not separate trust anchors | The trust boundary is the account; anchors do not partition it. |
| Creating trust anchors | Privileged, reviewed action | A new anchor widens what can reach every existing Roles Anywhere role. |
| Identity conditions | x509Issuer and SAN, over bare subject CN |
The CN also drives the source-identity prefix, which changes at 61 characters. |
| Conditioning on OU | Avoid equality on multi-valued RDNs | They flatten to one slash-joined string in certificate order. |
| Revocation | ImportCrl inside the revocation runbook |
No CDP or OCSP callbacks; AWS knows only what was imported. |
| Private CA validity changes | Always follow with UpdateTrustAnchor |
The enforced window is the one read at the last create or update. |
| Session ceilings | One profile per distinct ceiling | A profile carries many roles but only one session policy. |
The audit that finds the open path
One query, and it is cheap: list every role in the account whose trust policy names
rolesanywhere.amazonaws.com, and check each for a
Condition block at all — aws:SourceArn,
aws:SourceAccount, sts:SourceIdentity or a
certificate-attribute tag. A role with an unconditioned statement is reachable by every certificate every
registered CA has ever issued.
Then count trust anchors. One is a design. Several, created at different times by different teams, is the case the account trust boundary was written to warn about.
Closing Thought
Roles Anywhere is a good trade. Exchanging a certificate for a short-lived temporary session is strictly better than relying on an access key with no inherent expiry, and the mechanism does what it says. The thing to notice is where it moved the decision to.
With an access key, the authorisation story is entirely inside AWS and entirely visible to AWS tooling. With Roles Anywhere, half of it is in your PKI: which CA signs, what goes in the CN, how many OUs a certificate carries and in what order, when a revocation list was last exported. None of those are IAM changes, none of them appear in an IAM diff, and three of them can silently stop a condition from matching.
That makes the certificate template a security control, which is not where most organisations keep their
security controls. The practical consequence is small and specific: never leave the trust statement
unconditioned — name the anchor with aws:SourceArn when the role belongs
to one CA — and treat the certificate profile your CA issues from as part of the policy, because
that is what it is.
Security & Identity — AWS Private CA: what a private CA costs to operate rather than to create, why the hierarchy you choose is close to permanent, and where certificate lifetime stops being a security parameter and becomes an availability one.
Official AWS Reference
- The IAM Roles Anywhere trust model — required trust-policy actions, certificate field mapping, source-identity rules, signature validation and revocation
- The CreateSession API — session duration arithmetic, the role session name default and acceptRoleSessionName, and the relationship to AssumeRole
- What is IAM Roles Anywhere — trust anchors, profiles, and the account trust boundary
- AWS Private CA — further reading on operating the CA behind a trust anchor; no claims in this post are drawn from it
Comments