Documenting authorization changes
Authorization is critical to manage well. Understanding an API includes understanding not only what operations do, but when one is allowed to do them. Authorization changes, either new authorization constructs or new uses of existing authorization constructs, should be easy to find in a design rather than scattered through the document in individual sections.
In order to make it easy to see what (if any) authorization constructs are being modified in your design, we want to be able to find them in a single, clear place.
Note: This is not talking about RPC-level permissions, like those covered
RpcSecurityPolicy, but about authorization constructs used by your API for
its own purposes.
There are a couple of common types of authorization construct:
A role refers to an authorization construct which is granted to an
identity or an identity group on a resource. The most well known examples
of roles in G Suite are the
A permission refers to an authorization construct which is used to check
whether a particular identity can execute some operation. For example, to
check whether the current user can delete a file, the application may check
whether the user has the
file.delete permission on the file. Permissions are
most often assigned to roles, so that only roles are granted to identities or
identity groups, but some systems allow permissions to be granted directly.
Applications often only use each permission to authorize a single operation on
a resource, but there are cases where an application may use a permission to
authorize multiple different operations.
Within an application, authorization checks are made using only one of these
authorization constructs (typically permissions, if the application has that
concept). For example, in order to determine if a user can read a document, an
application would either check whether the user has a
or has the
reader role, but not both.
If your design creates new authorization constructs or extends/modifies the use of any existing authorization constructs, you must have a separate section in your design document that describes this. You may additionally discuss these in any other place in your document.
It is not important whether this is a top-level section or subsection. It is important that all such changes are listed together in a distinct section so they are easy to find and analyze.
If the identifier of an authorization construct that is new or modified is visible to users or developers, the way that it is identified should also be in your document. Examples of this are:
- If access is granted using roles and a new role is being added, the way that the role is identified in the role granting RPCs should be in your document.
- If there is an API that allows permissions assigned to roles to be manipulated, the way that the permission is identified in the role manipulation RPCs should be in your document.