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.

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 existence).

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.

Rationale

RFC 7231 §6.5.3 states that services are permitted to use 404 Not Found in lieu of 403 Forbidden in situations where the service does not want to divulge existence, whereas this AIP argues for the use of PERMISSION_DENIED (which corresponds to 403 Forbidden in HTTP) instead. We take this position for the following reasons:

• The practice of "getting 404 Not Found until you have enough permission to get 403 Forbidden" is counter-intuitive and increases the difficulty of troubleshooting.
  • A service could ameliorate this by sending information about missing permissions while still using the 404 Not Found status code, but this constitutes a mixed message.
• While 403 Forbidden is essentially always an error requiring manual action, 404 Not Found is often a valid response that the application can handle (e.g. "get or create"); overloading it for permission errors deprives applications of this benefit.
• RFC 7231 §6.5.4 states that 404 Not Found results are cacheable, but permission errors are not generally cacheable. Sending explicit cache controls on a conditional basis could ameliorate this, but would defeat the purpose.
• The guidance here is more consistent with most other real-world authorization systems.

Changelog

• 2021-05-11: Added a more detailed "Rationale" section.