feat: AIP-211 – Authorization checks (#30)

Author: Luke Sneeringer

aip/general/0211/aip.md

@@ -0,0 +1,72 @@
+# 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
+**should** error with `403 Forbidden`, 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 `404 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.
+
+## 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 existance, whereas this AIP argues for the use of `403 Forbidden`
+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.
+
+[rfc 7231 §6.5.3]: https://tools.ietf.org/html/rfc7231#section-6.5.3

aip/general/0211/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 211
+state: approved
+created: 2021-02-24
+placement:
+  category: design-patterns
+  order: 115