Using aliases for trust anchors, profiles, and CRLs
An alias is a readable name that you assign to a trust anchor, a
profile, or a certificate revocation list (CRL). Aliases make configuration easier to read and
to reuse. For example, a credential helper configuration that refers to a trust anchor by the
alias production-ca shows which certificate authority it uses. If you assign the
same alias to a trust anchor in each account and Region, your configurations differ only in the
account and Region.
A resource with an alias has an alias ARN, such as
arn:aws:rolesanywhere:us-east-1:111122223333:alias/trust-anchor/production-ca. The
resource also keeps its canonical ARN, which contains the resource ID. You
can use the alias ARN in place of the resource ID or the canonical ARN in many IAM Roles Anywhere
operations, including CreateSession and the credential helper. An alias ARN is
always a full ARN. You can't specify the alias name alone. For the list of operations, see
Use an alias ARN.
Use an alias ARN when you want your client to follow whichever resource currently holds the alias. Use the canonical ARN when your client must always use one specific resource, and in IAM policies and role trust policies. For recommendations, see Security recommendations for aliases.
An alias is a property of the resource, so you set, change, and remove it with the existing create, import, and update operations. For permissions, see Permissions and IAM policies for aliases.
Topics
Minimum versions to set and use an alias
To set, change, or remove an alias with the AWS CLI or an AWS SDK, you need a
version that supports the --alias-name option or the aliasName
parameter. The following table lists the minimum version for each tool.
Minimum versions to use an alias ARN with CreateSession
The following table lists the minimum version of the credential helper to use an alias
ARN as the trust anchor or profile in CreateSession.
| Tool | Minimum version | Notes |
|---|---|---|
| Credential helper | All versions (releases |
The --trust-anchor-arn and --profile-arn options
accept a canonical ARN or an alias ARN in every version, so you don't need to
upgrade the credential helper to use aliases. |
Manage an alias
You can set an alias when you create a trust anchor, profile, or CRL, or add one later. In
the console, enter a name in the optional Alias field for a trust anchor
or profile. In the AWS CLI or API, use the --alias-name option or the
aliasName parameter of the create, import, and update
operations.
In an update request, aliasName works as follows:
-
To set or change the alias, specify the new alias name. After the change, the previous alias ARN no longer identifies the resource.
-
To remove the alias, specify an empty string (
""). -
To keep the current alias, omit
aliasName.
A resource can't take an alias that another resource of the same type holds. To move an alias to a different resource, first remove it from the resource that holds it, and then set it on the other resource. Before you move an alias, read Considerations when you move an alias.
Manage an alias (console)
When you create or edit a trust anchor or a profile in the
IAM Roles Anywhere console
Manage an alias (AWS CLI)
You can manage the aliases of trust anchors, profiles, and CRLs with the AWS CLI by using
the --alias-name option. The following examples show how to create a profile
with an alias, change the alias of a trust anchor, and remove the alias of a CRL.
The following AWS CLI command creates a profile with the alias
web-servers:
PROMPT>aws rolesanywhere create-profile \ --nameweb-servers-profile\ --role-arnsarn:aws:iam::111122223333:role/WebServerRole\ --alias-name web-servers
The profile object in the response includes the alias and the alias ARN,
in addition to the profile ID and the canonical ARN.
{ "profile": { "profileId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222", "profileArn": "arn:aws:rolesanywhere:us-east-1:111122223333:profile/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222", "aliasName": "web-servers", "aliasArn": "arn:aws:rolesanywhere:us-east-1:111122223333:alias/profile/web-servers", "name": "web-servers-profile", ... } }
The following AWS CLI command changes the alias of a trust anchor to
production-ca-2027. The command identifies the trust anchor by its current
alias ARN:
PROMPT>aws rolesanywhere update-trust-anchor \ --trust-anchor-id arn:aws:rolesanywhere:us-east-1:111122223333:alias/trust-anchor/production-ca \ --alias-name production-ca-2027
The response contains "aliasName": "production-ca-2027" and
"previousAliasName": "production-ca".
The following AWS CLI command removes the alias of a CRL:
PROMPT>aws rolesanywhere update-crl \ --crl-ida1b2c3d4-5678-90ab-cdef-EXAMPLE33333\ --alias-name ""
The response doesn't contain aliasName or aliasArn, and it
contains the removed alias in previousAliasName.
Manage an alias (API)
The following table lists the operations that set or change an alias for each resource type.
| Resource | Set an alias when you create the resource | Set, change, or remove an alias later |
|---|---|---|
| Trust anchor | CreateTrustAnchor | UpdateTrustAnchor |
| Profile | CreateProfile | UpdateProfile |
| CRL | ImportCrl | UpdateCrl |
For the request syntax of each operation, see the IAM Roles Anywhere API Reference.
Use an alias ARN
You can use an alias ARN with the credential helper and CreateSession, and
with the operations that manage trust anchors, profiles, and CRLs. An alias ARN identifies a
resource only in the account and Region in the ARN, and it must be for the type of resource
that the parameter expects. For example, you can't use a profile alias ARN as a
trustAnchorId.
Use alias ARNs with the credential helper
The credential helper passes the trust anchor and profile ARNs to
CreateSession as you specify them, so you can configure it with alias ARNs.
As with canonical ARNs, the trust anchor and the profile must be in the same Region. The
following example shows a credential process configuration that uses alias ARNs:
[profile workload] credential_process = ./aws_signing_helper credential-process \ --certificate/path/to/certificate\ --private-key/path/to/private-key\ --trust-anchor-arn arn:aws:rolesanywhere:region:account:alias/trust-anchor/production-ca \ --profile-arn arn:aws:rolesanywhere:region:account:alias/profile/web-servers \ --role-arn arn:aws:iam::account:role/role-name-with-path
When CreateSession receives an alias ARN, IAM Roles Anywhere uses the trust anchor
or profile that holds the alias at the time of the request. If no trust anchor or profile
holds the alias, the request fails and no credentials are issued. The
aws:SourceArn value that IAM Roles Anywhere sets when it assumes the role is always the
canonical ARN of that trust anchor, even when the request used a trust anchor alias ARN.
Use alias ARNs in management operations
The following table lists the parameters that accept an alias ARN.
| Parameter | Operations | Accepted identifiers |
|---|---|---|
trustAnchorId |
GetTrustAnchor, UpdateTrustAnchor, DeleteTrustAnchor, EnableTrustAnchor, DisableTrustAnchor | Resource ID, canonical ARN, or alias ARN |
profileId |
GetProfile, UpdateProfile, DeleteProfile, EnableProfile, DisableProfile, PutAttributeMapping, DeleteAttributeMapping | Resource ID, canonical ARN, or alias ARN |
crlId |
GetCrl, UpdateCrl, DeleteCrl, EnableCrl, DisableCrl | Resource ID, canonical ARN, or alias ARN |
trustAnchorArn and profileArn |
CreateSession |
Canonical ARN or alias ARN |
Other parameters, such as the trustAnchorArn parameter of
ImportCrl, the trustAnchorId parameter of
PutNotificationSettings and ResetNotificationSettings, and the
resourceArn parameter of the tagging operations, don't accept alias ARNs. For
those parameters, use the identifier that the parameter's documentation describes.
The following AWS CLI command gets a trust anchor by its alias ARN:
PROMPT>aws rolesanywhere get-trust-anchor \ --trust-anchor-id arn:aws:rolesanywhere:us-east-1:111122223333:alias/trust-anchor/production-ca
If you call the IAM Roles Anywhere API directly instead of through an AWS SDK or the AWS CLI, URL-encode an ARN that you pass in the request path.
Security recommendations for aliases
An alias ARN identifies whichever resource holds the alias when IAM Roles Anywhere handles the request. Any operation that you call with an alias ARN, including a delete operation, acts on that resource. Anyone who can move an alias can therefore change which resource your clients use, as follows:
-
Trust anchors—Workloads that use a trust anchor alias ARN authenticate against the trust anchor that currently holds the alias. If the alias moves to a trust anchor for a different certificate authority, certificates from that certificate authority can authenticate through the same configuration.
-
Profiles—Sessions created with a profile alias ARN use the roles, session policies, and attribute mappings of the profile that currently holds the alias.
-
CRLs—Operations that use a CRL alias ARN, such as
UpdateCrl,DisableCrl, orDeleteCrl, act on the CRL that currently holds the alias.
To protect against an unexpected change of resource, we recommend the following:
-
In each role trust policy, use the
aws:SourceArncondition key with the canonical ARN of the trust anchor that you expect. The condition stays bound to that trust anchor, so moving a trust anchor alias doesn't let a different trust anchor assume the role. For more information, see Trust policy. -
Grant permission for the operations that set, change, or remove aliases only to the administrators who manage these resources. These operations are
CreateTrustAnchor,UpdateTrustAnchor,DeleteTrustAnchor,CreateProfile,UpdateProfile,DeleteProfile,ImportCrl,UpdateCrl, andDeleteCrl. For how IAM evaluates requests that use an alias ARN, see Permissions and IAM policies for aliases. -
When you remove an alias or delete the resource that holds it, any principal that can create or update a resource of the same type can claim the alias. If clients still use the alias ARN, set the alias on the replacement resource right away, or update those clients first.
-
Where a client must always use one specific resource, configure it with the canonical ARN instead of an alias ARN.
-
For operations that change or delete a specific resource, such as
DeleteTrustAnchororDisableProfile, identify the resource by its ID or canonical ARN, especially right after you move an alias. -
Alias names are case sensitive, so a near-duplicate alias such as
Production-CAandproduction-cacan identify two different resources and mislead anyone who reviews a configuration. Use one naming convention, for example lowercase letters only, and check for near-duplicate aliases before you create one.
Permissions and IAM policies for aliases
In IAM policies and VPC endpoint policies, specify trust anchors, profiles, and CRLs
by their canonical ARNs. In an IAM policy, a statement on a canonical ARN applies to every
request for that resource, whether the request uses the resource ID, the canonical ARN, or
the alias ARN. In a VPC endpoint policy, a CreateSession statement that names a
trust anchor by its canonical ARN also applies when the request uses the trust anchor's alias
ARN. In role trust policies, use the trust anchor's canonical ARN in the
aws:SourceArn condition.
Don't use an alias ARN in the Resource element of a policy. IAM accepts
the statement, but it has no effect: an Allow doesn't grant access, and a
Deny doesn't block it.
You can't write conditions on aliases. IAM Roles Anywhere doesn't provide condition keys for alias names or alias ARNs.
Aliases don't add IAM actions. To set, change, or remove an alias, you need permission
for the operation that creates or updates the resource, such as
rolesanywhere:UpdateTrustAnchor.
Considerations when you move an alias
Move an alias only when the new resource can replace the old one for every client that uses the alias ARN, for example when you re-create a trust anchor or profile from infrastructure as code. For a trust anchor, the new trust anchor must accept the same certificates as the old one. An alias can't cover a period when both resources must be active, such as a certificate authority rotation. In that case, configure clients with canonical ARNs.
Before you move an alias, consider the following:
-
A move takes two updates. You remove the alias from one resource, and then set it on the other. Between the two updates, requests that use the alias ARN fail.
-
A change can take a short time to take effect. During that time, the alias ARN might still resolve to the previous resource or might not resolve yet.
-
Credentials that IAM Roles Anywhere already issued remain valid until they expire.
For security recommendations, see Security recommendations for aliases.
Aliases in CloudTrail logs
CloudTrail records the aliasName parameter that you send to the create, import, and
update operations, and the aliasName, aliasArn, and
previousAliasName fields in the responses of those operations. Error messages
that name an alias, such as the message for an alias that is already in use, also appear in
CloudTrail events.
When a CreateSession request identifies the trust anchor or profile by its alias
ARN, the alias ARN appears in the CloudTrail event for that request.
Anyone who can read your CloudTrail events can see your alias names. For more information about
IAM Roles Anywhere and CloudTrail, see CloudTrail logs.
Alias reference
Alias ARN format
An alias ARN has the following format:
arn:partition:rolesanywhere:region:account:alias/resource-type/alias-name
The resource-type is trust-anchor,
profile, or crl. The alias ARN doesn't replace the canonical ARN. A resource with an alias has
both ARNs, and IAM Roles Anywhere returns both.
The following table shows example canonical and alias ARNs for each resource type.
| Resource | Canonical ARN | Alias ARN |
|---|---|---|
| Trust anchor | arn:aws:rolesanywhere:us-east-1:111122223333:trust-anchor/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 |
arn:aws:rolesanywhere:us-east-1:111122223333:alias/trust-anchor/production-ca |
| Profile | arn:aws:rolesanywhere:us-east-1:111122223333:profile/a1b2c3d4-5678-90ab-cdef-EXAMPLE22222 |
arn:aws:rolesanywhere:us-east-1:111122223333:alias/profile/web-servers |
| CRL | arn:aws:rolesanywhere:us-east-1:111122223333:crl/a1b2c3d4-5678-90ab-cdef-EXAMPLE33333 |
arn:aws:rolesanywhere:us-east-1:111122223333:alias/crl/revocation-prod |
In the TrustAnchorDetail, ProfileDetail, and
CrlDetail objects that IAM Roles Anywhere returns, the alias is in the
aliasName field and the alias ARN is in the aliasArn field. Both
fields are present only when the resource has an alias.
Alias naming rules
Alias names appear in CloudTrail logs and in the responses of IAM Roles Anywhere operations. Don't put confidential or sensitive information in an alias name. For more information, see Aliases in CloudTrail logs.
An alias name must meet the following requirements:
-
It contains 1 to 256 characters.
-
It begins with a letter (A-Z or a-z).
-
It contains only letters (A-Z and a-z), numbers (0-9), underscores (_), hyphens (-), and forward slashes (/). Periods (.), spaces, and other characters aren't allowed.
-
A forward slash can appear only between two other characters. An alias name can't end with a forward slash or contain two forward slashes in a row. For example,
prod/web-serversis valid, andprod/andprod//web-serversaren't. -
It doesn't begin with
aws/, in any combination of uppercase and lowercase letters. IAM Roles Anywhere reserves this prefix.
Uniqueness
An alias name must be unique among the resources of the same type in your AWS account and Region. You can use the same alias name for a trust anchor and a profile, or for trust anchors in different Regions, because their alias ARNs differ.
Case sensitivity
Alias names are case sensitive. Production-CA and
production-ca are different aliases, and two trust anchors can hold them at the
same time. An alias ARN identifies a resource only when its alias name matches the case of the
alias exactly. For a naming recommendation, see
Security recommendations for aliases.
Limits
Each trust anchor, profile, or CRL can have at most one alias. Aliases don't have their own quota.
Alias behavior and error reference
The previousAliasName field
When an update changes or removes an existing alias, the response includes
previousAliasName, which contains the alias that the resource had before the
request. The response doesn't include previousAliasName when the alias is
unchanged or when the resource had no alias before the request. Other operations don't
return it.
An alias ARN that no resource holds
If a request names an alias ARN that no resource holds, the error depends on your permissions:
-
If your policies allow the action on every resource of that type, IAM Roles Anywhere returns
ResourceNotFoundException. For trust anchors, for example, that means aResourceelement ofarn:aws:rolesanywhere:.region:account:trust-anchor/* -
Otherwise, IAM Roles Anywhere returns
AccessDeniedException.
This applies to the trustAnchorId, profileId, and
crlId parameters.