AIP-211
Authorization checks
The majority of operations, whether reads or writes, require authorization: permission to do the thing the user is asking to do. Additionally, it is important to be careful how much information is provided to unauthorized users, since leaking information can be a security concern.
Guidance
Services must check authorization before validating any request, to ensure both a secure API surface and a consistent user experience. An operation may require multiple permissions or preconditions in order to grant authorization.
If a request can not pass the authorization check for any reason, the service
must error with PERMISSION_DENIED
, and the corresponding error message
should look like: "Permission {p}
denied on resource {r}
(or it might
not exist)." This avoids leaking resource existence.
Note: This guidance conflicts with the guidance in the HTTP specification,
which argues for the use of 404 in cases where the user lacks permission to
know whether or not a resource exists. This variance is because of real-world
challenges: the practice of "getting NOT_FOUND
until you have enough
permission to get PERMISSION_DENIED
" is counter-intuitive and increases the
difficulty of troubleshooting. Additionally, the guidance here is more
consistent with most other real-world authorization systems.
If it is not possible to determine authorization for a resource because the
resource does not exist, the service should check authorization to read
children on the parent resource, and return NOT_FOUND
if the authorization
check passes.
Multiple operations
A service could encounter a situation where it has two different operations with two different permissions, either of which would reveal the existence of a resource if called, but a user only has permission to call one of them.
In this situation, the service should still only check for authorization applicable to the operation being called, and should not try to "help out" by checking for related authorization that would provide permission to reveal existence, because such algorithms are complicated to implement correctly and prone to accidental leaks.
For example, posit a scenario where:
- A resource exists within a given collection that a user is unable to read.
- The user does have the ability to create other resources, and the collection uses user-specified IDs (meaning that a failure because of a duplicate ID would reveal existance).
In this situation, the get or create methods should still only check their permissions when determining what error to return, and not one another's.