Official documentation source for the AWS Identity and Access Management (IAM) User Guide
License: MIT No Attribution
This repository is archived, read-only, and no longer updated. For more information, read the announcement on the AWS News Blog.
You can find up-to-date AWS technical documentation on the AWS Documentation website, where you can also submit feedback and suggestions for improvement.
Example Scenario Using Separate Development and Production Accounts includes this image:
This language is inconsistent with other documentation, where roles are assumed and not called.
See 3a0537e#diff-c67a92ada731432c8bc051338cd661f9R58
Change /mgmt/mgmt/ back to /mgmt/ . This is all over the last commit.
There doesn't appear to be a document that lists all AWS services that can be defined in a service principal element of trust policy. A few that I'm aware of are:
The only way to get the service principal name that I've found are using the IAM console. Which I'll admit is not very direct and involves more steps than desired:
Having a document that lists all service principal names would be a killer feature, and allow us to self-service inquiries as to what service is being allowed. As I'm sure not all service names are easy as ec2/cloudtrail/config.
I apologize if I somehow missed this, but comparing to RDS or EC2, IAM isn't super clear about which resource-level permissions (and/or condition keys) apply to which API actions. The most I could find in the IAM user guide was some extended examples in here, and a few more examples under this heading. But for example, if I want to know which resources (if any) apply to iam:CreateRole or whether I can scope iam:GetRole permissions to a particular role resource, I don't think that's mentioned anywhere except implicitly in the policy editor.
It would be really nice to get a similar table of all valid IAM actions, what resources they apply to, and which condition keys are relevant to them. This page could also make it clear that GetCallerIdentity is special and can't be restricted.
Or have I just missed a place where this material is covered?
Thanks!
As you know, troubleshooting problems with IAM and its many moving parts can be a challenge. What issues have you run into and solved? Can you share your solution with your peers? Please share only problems for which you've found a solution. If you're still struggling with a problem, please contact Customer Support or post your issue on the AWS Forums.
Share the following information with the IAM doc team as a response to this issue, and we'll consider adding it to the troubleshooting section of the AWS IAM documentation.
On behalf of all of your colleagues who run into the same problems, we thank you for your participation.
Stephenie Swope
Senior Technical Writer
AWS Identity and Access Management
Carla Spoon
Technical Writer
AWS Identity and Access Management and AWS Organizations
https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awssupport.html
This is unclear.
The lines AWS Support does not let you allow or deny access to individual actions; therefore your policy must use the "Action": "support:*" to use the AWS Support Center or to use the AWS Support API. and You can specify the following actions in the Action element of an IAM policy statement. By using policies, you define the permissions for anyone performing an operation in AWS conflict with each other.
On top of that, from the IAM policy console - it seems that I can actually list specific actions for support.
We tried to use the IAM action kms:CreateAlias with a key as a resource as specified here: https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awskeymanagementservice.html#awskeymanagementservice-actions-as-permissions
The Stack failed with:
User: arn:aws:sts::***:assumed-role/***/AWSCloudFormation
is not authorized to perform: kms:CreateAlias on resource:
arn:aws:kms:eu-west-1:***:alias/***
After adding alias/* to the resources, everything worked as expected.
This document AWS Global Condition Context Keys raises more questions than addresses. There are 12 global conditions that are lacking pretty critical pieces of information of what AWS services they're compatible with:
This condition key is available for only some services
Aside from using time consuming trial by fire unit testing. How are customers expected to know which services are compatible with these conditions? It appears IAM knows of the services, and if so a 1:1 mapping of compatible services to global conditions should be present. This would greatly help with reducing unnecessary policy testing.
Similar problem for the 2 global tag conditions (different wording):
Check your service to see whether it supports using this condition key.
It was mentioned/announced in the new SCP release but not fully specified and I don't think it's made it into the documentation yet.
Here are questions that come to mind as a user:
Principal element but it's probably not obvious to folks when they might want one vs. the other (cover the counterintuitive behavior of Deny on NotPrincipal and such)aws:PrincipalArn behave on non-AWS principals? I'm talking principals from the Service namespace, Federated namespace, and so on. Is it unset? Set but unspecified? Should we assume it's always set when aws:userid is set?The existing minimal documentation at https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html just mentions very briefly that it's a condition key and works with string operators (doesn't mention ARN operators, which I think are a better fit for it and still work) and doesn't cover any of the deeper semantics.
"Attach managed and inline policies to IAM identities, such as users, groups to which users belong, and roles."
At some other place you write that groups are no prinicipals and as such it is not possible to attach policies directly to groups. The policies are attached to the users indirectly.
In the ARC page for CloudWatch Events, we only see one type of resource, for rule. But if you poke around CloudWatch Event Bus policies, there appears to be another "resource" for the event bus itself:
$ aws events describe-event-bus --output text --query Policy | python -mjson.tool
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "e18039e0-d668-11e8-bcd2-354ccfb68e3b1540260658302",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:root"
},
"Action": "events:PutEvents",
"Resource": "arn:aws:events:us-east-1:123456789012:event-bus/default"
}
]
}
I haven't tested how sensitive PutEvents is to the event-bus resource (i.e., will I be limited from putting events to an external account?) but it seems like it should at least be listed in the resources for CWE, and probably for the PutEvents action as well.
I was unsure whether to file this against the IAM docs repo or the CWE one, but I figured that since the ARC pages live under the IAM namespace it would make more sense to send here. If you think it belongs on the other side I can cross-post over there.
In the Actions Defined by AWS Resource Access Manager section, all the links in the table (in the Action column, such as CreateResourceShare or DeleteResourceShare) that are supposed to link to the API actually all redirect here: https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Welcome.html.
This is because all the RAM links have since been moved to a different section. The old links still point to https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateResourceShare.html where they should point to https://docs.aws.amazon.com/ram/latest/APIReference/API_CreateResourceShare.html
(ram should be the new high level path directory instead of AWSEC2)
Currently, all three of the APIs claim in the documentation indirectly to include the permissions boundary: although the included example output does not have a boundary in it, if you click on the RoleDetail link on the GetAccountAuthorizationDetails doc under RoleDetailList.member.N, it'll claim that it includes PermissionsBoundary when in fact it's not there. Same with the equivalent doc pages for ListRoles and ListUsers.
Could the docs be clarified to specify that the boundary is not returned in these cases? It had me quite confused for a while because I thought what I was seeing meant a permission boundary was not present on the returned roles, when in fact I just needed to issue a separate GetRole to find out about the boundary.
Alternately (and more usefully), it would be nice if the APIs lived up to their current documentation and did return boundary information 😄but if that can't be done, it would be nice if the docs pointed it out explicitly.
This permission is missing a description and also does not have a link to the API documentation either.
I did find the following referencing ObjectOwnerOverrideToBucketOwner: https://docs.aws.amazon.com/AmazonS3/latest/dev/crr-change-owner.html
ECS API docs and the CLI ref have been updated to reflect new TagResource and UntagResource actions for ECS, but the IAM documentation has not.
TagResource to the ECS IAM actions listUntagResource to the ECS IAM actions listCredit to @robertd for the discovery.
S3 Condition keys page has multiple missing descriptions in the key table towards end of the page.
Also, s3:locationconstraint has two entries, one all lowercase and one camel-case. I don't think there is a difference between both entries.
There's a particular sentence in Section ...IfExists Condition Operators of the IAM JSON Policy Elements: Condition Operators documentation that's I'm having a hard time wrapping my head around.
If the policy key is present in the context of the request, process the key as specified in the policy. If the key is not present, evaluate the condition element as true.
Applying this statement to the below bucket policy, I interrupt this to mean
All s3:PutObject requests from accounts (including master) within the organization 'foo' are explicitly DENIED. The EC2 service is ALLOWED to use s3:PutObject.
If the key (Organization ID = foo) is not present the condition is TRUE, so IAM will explicitly DENY all AWS accounts. Including internal accounts associated with a service principal name.
{
"Version": "2012-10-17",
"Statement": [{
"Principal": "*",
"Effect": "Deny",
"Action": "s3:PutObject",
"Resource": "*",
"Condition": {
"StringLikeIfExists": {
"aws:PrincipalOrgID": "foo"
}
}
},
{
"Principal": {"Service": "ec2.amazonaws.com"},
"Effect": "Allow",
"Action": "s3:PutObject",
"Resource": "*"
}
]
}
The following text in doc_source/reference_policies_condition-keys.md has always confused me:
Do not use a policy construct similar to the following to check whether the MFA key is present:
##### THIS EXAMPLE DOES NOT WORK ##### "Action" : "Deny", "Condition" : { "Null" : { "aws:MultiFactorAuthPresent" : true } }You might expect the previous example to deny access if MFA is not used. However, when you make an API request with long-term credentials (access keys), the MFA condition context keys are always missing. Consequently, testing for MFA this way always results in denied access to long-term credentials.
Doesn't the last sentence of "testing for MFA this way always results in denied access to long-term credentials" confirm that the example does in fact "deny access if MFA is not used" and thus the thing that we might expect is in fact an accurate expectation? And thus, isn't the example a perfectly reasonable and valid way to deny all access unless MFA auth is used? It has been a few years since I've tested, but I seem to recall that it worked exactly as I expected.
The other day I came across two IAM documents discuss global condition keys:
The document AWS Global Condition Context Keys seems to be the better choice for in depth information. Consider removing the conditions & their descriptions from IAM Policy Elements: Variables and just link to AWS Global Condition Context Keys?
One more thing, the document IAM Policy Elements: Variables has unique information that the condition aws:UserAgent should only be used with the AWS CLI and not for restricting a web browser:
aws:UserAgent This value is a string that contains information about the requester's client application. This string is generated by the client and can be unreliable. You can only use this context key from the AWS CLI.
Can we get this unique information added to AWS Global Condition Context Keys
Looking at https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsamplify.html on the web which maps to https://github.com/awsdocs/iam-user-guide/blob/master/doc_source/list_awsamplify.md here, I have some errors / comments:
https://docs.aws.amazon.com//amplify/latest/user-guide/welcome.html) which break when clickeds in the domains resource type ARN (e.g. apps/${AppId}/domainss/${DomainName} )I was scanning this list and noticed that the naming for all the individual services is pretty inconsistent. I've also noticed this elsewhere in the AWS IAM world (like the online policy editor, which has the same names):
Contrast the following:
Basically, inconsistency between whether the service is called "AWS" or "Amazon" (or neither, in the case of IAM or SSO), and sometimes a seemingly redundant "service" is added to the end of the name. The "Manage Amazon API Gateway" one is weird too.
Luckily it seems like the list is alphabetized by the important bit, but the inconsistent prefix (lengths vary) makes it very hard to visually scan the list looking for something.
I assume these names reflect some sort of internal organizational details but it's confusing for users and I was wondering if something could be done to improve consistency in the IAM documentation at least.
Identity-Based Policies and Resource-Based Policies
Resource-based policies differ from resource-level permissions. You can attach resource-based policies directly to a resource, as described in this topic. Resource-level permissions refer to the ability to use ARNs to specify individual resources in a policy. Resource-based permissions are supported only by some AWS services.
In the note that's there to clarify the difference between (1) Resource-based policies and (2) Resource-level permissions, there shouldn't be references to (3) Resource-based permissions. (Unless the intention is to underscore on some meta-level just how confusing this all is.)
In https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html, it talks extensively about what it means to enable or disable STS endpoints in a given region. The document says
All regions are enabled by default, but you can disable any regions that you know you don't need.
at the top and that's what I find unclear. As an administrator of an account, it's unclear to me why I'd actually want to disable STS endpoints I don't need. Does disabling them come with a security benefit of some sort? Is it just a sense of cleanliness and efficiency of not leaving stuff turned on that I don't need?
Could the manual perhaps go into some detail about what kinds of scenarios might warrant disabling STS endpoints? I feel like a confused user might interpret disabling regional STS endpoints as disabling regions they don't use (which has valid use cases), which is definitely not the case.
Sample IAM policies for Session Manager demonstrate instance id resource support as well as condition key support for the StartSession command. The IAM documentation for the action reflects neither. This can mislead developers into believing that StartSession must accompany Resource: "*" and will not support any conditions.
instance to the resource types for StartSessionssm:resourceTag/tag-key to the condition keys for StartSessionThe Condition key here for ram:AllowsExternalPrincipals states that resource shares can only be acted on if the share allows external principals, but isn't clear on what is an external principal.
From this page, https://docs.aws.amazon.com/ram/latest/userguide/control-access.html I can infer that external principals are AWS accounts that are outside of its AWS organization.
Would be good to be clear on this page for condition keys.
There is an infinite loop in documentation about AWS Global Condition Context.
aws:RequestedRegion condition key (and others) is defined as available for only some services but it is impossible to find out which ones as there is a note To learn whether a service supports one of these condition keys, you must view the documentation for that service.
Unfortunately such info is not in service documentation. E.g. WorkDocs redirects back to global context keys as it has no service-specific context keys.
What exactly does this limited availability means? It is not clear from this documentation.
For API calls, whenever service is global or not, aws:RequestedRegion should be supported.
How/where we can find the list of services where such keys [aws:RequestedRegion] are not supported (useful for policy creation)?
Many thanks for clarifying it and mentioning it in documentation.
In the English text for this documentation page, it says
This data type can only have a value of
Policy.
However, a couple of lines down, it then claims
Valid Values:
PermissionsBoundaryPolicy
The former is correct. For example, calling GetRole on one of my roles with a boundary on it, returns
"PermissionsBoundary": {
"PermissionsBoundaryType": "Policy",
"PermissionsBoundaryArn": "arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess"
}Missing IAM Action states:TagResource in the documentation https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsstepfunctions.html.
StepFunctions started to support resource tagging from Jan 7th 2019 as per the documentation https://docs.aws.amazon.com/step-functions/latest/dg/document-history.html
However the IAM permission document is not updated with the recent updates and changes to StepFunction permissions.
Please update the documentation so that users are aware about the new IAM Action available for StepFunctions
It's very difficult to understand, what action type every action has.
This issue was created only for self-fixing this issue. I will create pull request with changes for two days.
With best regards, me!
Now that SMS (preview) is being discontinued perhaps this should be marked in the documentation in some way?
GetContextKeysForPrincipalPolicy on this page: https://docs.aws.amazon.com/IAM/latest/UserGuide/list_identityandaccessmanagement.html takes me to https://docs.aws.amazon.com/IAM/latest/APIReference/Welcome.html where it should take me to the API reference for iam:GetContextKeysForPrincipalPolicy (which is here: https://docs.aws.amazon.com/IAM/latest/APIReference/API_GetContextKeysForPrincipalPolicy.html)
The secrets manager docs at https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awssecretsmanager.html contain content not listed in this repo. I noticed two mistakes. In the row for GetRandomPassword, passowrd is spelled incorrectly, and the access level is listed as write instead of read.
The policy at https://github.com/awsdocs/iam-user-guide/blob/master/doc_source/reference_policies_examples_s3_cognito-bucket.md claims that it restricts Cognito users' access to only objects containing their Cognito ID. This is true for the second statement, but the first statement is missing the Cognito ID in its prefix condition. This means that the user will be able to enumerate all users' objects, though it will not be able to access them. Either the prefix condition should be updated, or the surrounding text should be revised to reflect the broader permissions in the policy.
It appears in the latest periodic update that a large number of documentation files were removed: 2b1fa38
For example the reference_policies_elements* files have gone, so the documentation for this page: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html appears to be missing.
According to https://docs.aws.amazon.com/systems-manager/latest/userguide/auth-and-access-control-iam-access-control-identity-based.html#policy-conditions, AWS Systems Manager supports the following condition keys:
ssm:resourceTag/*ssm:Recursivessm:OverwriteBut https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awssystemsmanager.html (code) only mentions the first one.
The docs do not mention the fact that the master account of an organization (which in other parts of the console/docs is considered or treated as a "member" of the org) won't match this condition.
Documentation on the s3:HeadBucket action is missing from the IAM documentation. The API call itself is documented.
Credit to @rosswickman for finding the issue.
Sorry to keep submitting these ARC issues here but there's not really a good place for me to submit them otherwise!
A handful of ARC pages for services include iam:PassRole as a dependent action, but it seems like most actions that depend on iam:PassRole don't list it as a dependent action. As usual, this is due to missing data from all the service-specific permission data files, but given that it's so pervasive across different services, it's also probably relevant to IAM.
Here's a few common ones off the top of my head that aren't listed on the ARC pages:
ec2:RunInstanceslambda:CreateFunction and lambda:UpdateFunctionConfigurationcodebuild:CreateProject and codebuild:UpdateProject (documented here but not in the ARC page for CodeBuild)I assume there are others but those are the ones I happened to be looking at. Not all of them are missing, including some of the lesser known services like dax:CreateCluster and sms-voice:CreateConfigurationSetEventDestination.
ListTags on this page https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awslambda.html goes to a broken link (https://docs.aws.amazon.com/lambda/latest/dg/API_ListTagsForResource.html). This should direct to https://docs.aws.amazon.com/lambda/latest/dg/API_ListTags.html
From going through the Evaluating Identity-Based Policies with Resource-Based Policies, I noticed the following: If an action is allowed by an identity-based policy, a resource-based policy, or both, then AWS allows the action.
However, that is not the case with KMS key policies.
From KMS documentation (https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html):
For most AWS services, IAM policies are the only way to control access to the service's resources. Some services offer resource-based policies or other access control mechanisms to complement IAM policies, but these are generally optional and you can control access to the resources in these services with only IAM policies. This is not the case for AWS KMS, however. To allow access to a KMS CMK, you must use the key policy, either alone or in combination with IAM polices or grants. IAM policies by themselves are not sufficient to allow access to a CMK, though you can use them in combination with a CMK's key policy.
The policy evaluation logic should have a disclaimer that KMS does not function similarly and is an exception to the logic that is stated above (If an action is allowed by an identity-based policy, a resource-based policy, or both, then AWS allows the action)
Hello,
I have noticed a lot of discrepencies between IAM and Glue actions reference.
Example: BatchStopJobRun is not reference in IAM documentation regarding Glue but it is referenced in Glue API reference.
Although a lot of details are missing for condtions and resource in the IAM documentation.
https://docs.aws.amazon.com/glue/latest/dg/api-permissions-reference.html
Regards,
Joseph de Clerck
If you check this document on IAM condition keys, you'll see the following text:
This value can be any string, such as a passphrase or account number. Because a cross-account role is usually set up to trust everyone in an account, the administrator of the trusting account might send an external ID to the administrator of the trusted account. That way, only someone with the ID can assume the role, rather than everyone in the account.
This seems to be suggesting to add a role trust policy targeting an entire account and then to use the ExternalId as a secret to guard access, which isn't really the intended use and also isn't safe. Indeed, the page it references right after that passage has a big loud warning right at the top telling users not to treat ExternalId as a secret:
Important
AWS does not treat the external ID as a secret. After you create a secret like an access key pair or a password in AWS, you cannot view them again. The external ID for a role can be seen by anyone with permission to view the role.
Can the documentation on this page be amended to not suggest an unsafe use of the field? Anyone with CloudTrail access could trivially circumvent the scheme described there. It seems better to immediately reference the confused deputy problem and tell people to read the longer page to learn more about it.
SSM API docs and the CLI ref include all available permissions, but the IAM reference does not.
doc_source/list_awssystemsmanager.md
https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_Operations.html
https://docs.aws.amazon.com/cli/latest/reference/ssm/index.html
Add the following permissions to the IAM documentation:
At 3a0537e#diff-fbf230b30ebe782d4a10b76ae6ad9b20R37 you need a comma after "iam:GetAccountSummary" otherwise the json is invalid.
I just filed awsdocs/amazon-cloudwatch-user-guide#25 against CloudWatch, but upon further inspection it seems like the ARC pages aren't terribly consistent in how they treat that condition.
For example, the EC2 page lists ec2:ResourceTag/${TagKey} 145 times across the page on every action that supports it. On the other hand, the IAM page (and the CloudWatch page from the ticket above) seems to only list it in the resource table, as far as I understand it, implying that whenever that resource is used, the ec2:ResourceTag/${TagKey} condition key is available on it.
Both of the approaches seem fine but it was confusing to me to see both in use across these autogenerated ARC pages. Is there a meaningful difference between the two of them or is this accidental?
Hello at this link:
https://docs.amazonaws.cn/en_us/IAM/latest/UserGuide/id_roles_use_switch-role-console.html
You can manually construct the link and then skip to step Step 5 in the following procedure. To construct your link, use the following format:
The url specification is wrong, it should be without "www":
https://signin.amazonaws.cn/switchrole?account=account_id_number&roleName=role_name&displayName=text_to_display
I appreciated the big warning in the aws:Referer section of this page, explaining that it's provided through a remote HTTP header and thus does not provide a strong security guarantee.
It seems like a similar warning applies to aws:UserAgent, which currently just says "Checks the requester's client application", and thus might cause an unsuspecting IAM policy writer who is not familiar with how HTTP works to think it's somehow trustworthy.
I know SNS has aws:SourceOwner as an available key for SNS. However, I don’t see this in any AWS documentation (For SNS keys or global keys). This is in the default SNS access policy applied to topics.
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.