Document that GetAccountAuthorizationDetails, ListRoles, and ListUsers do not return boundaries

[copumpkin]

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.

[copumpkin]

There's at least one example of someone else being confused by this, judging by this SO post.

[stephswo]

I've contacted the IAM API team and they're checking into this. We can't change the API docs manually. That information comes from the API model that the team owns.

[copumpkin]

Thank you, that makes sense. Can we keep this open so as to follow the status of it? I'd be more happy if the APIs were amended to follow their current spec (since otherwise it currently takes a ton of speculative GetRole calls to figure out which roles have boundaries), but amending the spec to match the implementation would also be acceptable.

[copumpkin]

Until this is fixed, for anyone who comes across this issue, it's actually possible to bulk retrieve all permission boundaries without speculatively issuing one GetRole/GetUser for every principal in the account:

1. If you list all IAM policies (either via GetAccountAuthorizationDetails or ListPolicies), there's a special PermissionsBoundaryUsageCount entry for each result
2. Pick the ones with PermissionsBoundaryUsageCount above 0, and issue a ListEntitiesForPolicy against those policy ARNs, with PermissionsBoundary as a policy usage filter
3. Join those results (either by principal ID for maximum safety, or by name) against your list of principals

Which basically means you now have O(permission boundary policy usage count) API calls to make instead of the much larger O(principals) you'd have with GetRole or GetUser. Of course, returning this information in the APIs that claim to provide it would be even better and more efficient, but the approach I describe here is actually pretty fast in practice.

[stephswo]

The IAM team is still trying to determine a non-breaking solution.

[ljquin]

Thanks for reporting this issue! Unfortunately, the list operation and the get operation both return the same data type. This was an early API model decision and one that we're stuck with today. The only way to fix it is to rewrite the API model to ensure that each operation returns a different data type and release a new version of the API. The API, CLI, and SDK documentation sets all come from the API model.

The IAM team is aware of this issue and is investigating a path forward. You can contact AWS Premium Support at any time to request an update for this issue.