This AIP is currently under review. This means that the editors have read it and are in high-level concurrence, and while it is not yet fully approved, we have a good faith expectation that the AIP will be approved in something close to its current state.

AIP-2715

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 by RpcSecurityPolicy, but about authorization constructs used by your API for its own purposes.

Definitions

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 commenter, reader, writer, and owner roles from Drive.

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 doc.read permission or has the reader role, but not both.

Guidance

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.