Permission Resources

Users

A user is an identity to be authenticated. Each user can have multiple roles. The user has a capability (such as reading or writing) on the resource if one of the roles has that capability.

A user named root is required before authentication can be enabled, and it always has the ROOT role. The ROOT role can be granted to multiple users, but root is required for recovery purposes.

Roles

Each role has exact one associated Permission List. An permission list exists for each permission on key-value resources.

The special static ROOT (named root) role has a full permissions on all key-value resources, the permission to manage user resources and settings resources. Only the ROOT role has the permission to manage user resources and modify settings resources. The ROOT role is built-in and does not need to be created.

There is also a special GUEST role, named 'guest'. These are the permissions given to unauthenticated requests to etcd. This role will be created automatically, and by default allows access to the full keyspace due to backward compatibility. (etcd did not previously authenticate any actions.). This role can be modified by a ROOT role holder at any time, to reduce the capabilities of unauthenticated users.

Permissions

There are two types of permissions, read and write. All management and settings require the ROOT role.

A Permission List is a list of allowed patterns for that particular permission (read or write). Only ALLOW prefixes are supported. DENY becomes more complicated and is TBD.

Key-Value Resources

A key-value resource is a key-value pairs in the store. Given a list of matching patterns, permission for any given key in a request is granted if any of the patterns in the list match.

Only prefixes or exact keys are supported. A prefix permission string ends in *.
A permission on /foo is for that exact key or directory, not its children or recursively. /foo* is a prefix that matches /foo recursively, and all keys thereunder, and keys with that prefix (eg. /foobar. Contrast to the prefix /foo/*). * alone is permission on the full keyspace.

Settings Resources

Specific settings for the cluster as a whole. This can include adding and removing cluster members, enabling or disabling authentication, replacing certificates, and any other dynamic configuration by the administrator (holder of the ROOT role).

v2 Auth

Basic Auth

We only support Basic Auth for the first version. Client needs to attach the basic auth to the HTTP Authorization Header.

Authorization field for operations

Added to requests to /v2/keys, /v2/auth
Add code 401 Unauthorized to the set of responses from the v2 API
Authorization: Basic {encoded string}

Future Work

Other types of auth can be considered for the future (eg, signed certs, public keys) but the Authorization: header allows for other such types