go.etcd.io/etcd@v3.3.27+incompatible/Documentation/op-guide/authentication.md (about)

     1  ---
     2  title: Role-based access control
     3  ---
     4  
     5  ## Overview
     6  
     7  Authentication was added in etcd 2.1. The etcd v3 API slightly modified the authentication feature's API and user interface to better fit the new data model. This guide is intended to help users set up basic authentication and role-based access control in etcd v3.
     8  
     9  ## Special users and roles
    10  
    11  There is one special user, `root`, and one special role, `root`.
    12  
    13  ### User `root`
    14  
    15  The `root` user, which has full access to etcd, must be created before activating authentication. The idea behind the `root` user is for administrative purposes: managing roles and ordinary users. The `root` user must have the `root` role and is allowed to change anything inside etcd.
    16  
    17  ### Role `root`
    18  
    19  The role `root` may be granted to any user, in addition to the root user. A user with the `root` role has both global read-write access and permission to update the cluster's authentication configuration. Furthermore, the `root` role grants privileges for general cluster maintenance, including modifying cluster membership, defragmenting the store, and taking snapshots.
    20  
    21  ## Working with users
    22  
    23  The `user` subcommand for `etcdctl` handles all things having to do with user accounts.
    24  
    25  A listing of users can be found with:
    26  
    27  ```
    28  $ etcdctl user list
    29  ```
    30  
    31  Creating a user is as easy as
    32  
    33  ```
    34  $ etcdctl user add myusername
    35  ```
    36  
    37  Creating a new user will prompt for a new password. The password can be supplied from standard input when an option `--interactive=false` is given. `--new-user-password` can also be used for supplying the password.
    38  
    39  Roles can be granted and revoked for a user with:
    40  
    41  ```
    42  $ etcdctl user grant-role myusername foo
    43  $ etcdctl user revoke-role myusername bar
    44  ```
    45  
    46  The user's settings can be inspected with:
    47  
    48  ```
    49  $ etcdctl user get myusername
    50  ```
    51  
    52  And the password for a user can be changed with
    53  
    54  ```
    55  $ etcdctl user passwd myusername
    56  ```
    57  
    58  Changing the password will prompt again for a new password. The password can be supplied from standard input when an option `--interactive=false` is given.
    59  
    60  Delete an account with:
    61  ```
    62  $ etcdctl user delete myusername
    63  ```
    64  
    65  
    66  ## Working with roles
    67  
    68  The `role` subcommand for `etcdctl` handles all things having to do with access controls for particular roles, as were granted to individual users.
    69  
    70  List roles with:
    71  
    72  ```
    73  $ etcdctl role list
    74  ```
    75  
    76  Create a new role with:
    77  
    78  ```
    79  $ etcdctl role add myrolename
    80  ```
    81  
    82  A role has no password; it merely defines a new set of access rights.
    83  
    84  Roles are granted access to a single key or a range of keys.
    85  
    86  The range can be specified as an interval [start-key, end-key) where start-key should be lexically less than end-key in an alphabetical manner.
    87  
    88  Access can be granted as either read, write, or both, as in the following examples:
    89  
    90  ```
    91  # Give read access to a key /foo
    92  $ etcdctl role grant-permission myrolename read /foo
    93  
    94  # Give read access to keys with a prefix /foo/. The prefix is equal to the range [/foo/, /foo0)
    95  $ etcdctl role grant-permission myrolename --prefix=true read /foo/
    96  
    97  # Give write-only access to the key at /foo/bar
    98  $ etcdctl role grant-permission myrolename write /foo/bar
    99  
   100  # Give full access to keys in a range of [key1, key5)
   101  $ etcdctl role grant-permission myrolename readwrite key1 key5
   102  
   103  # Give full access to keys with a prefix /pub/
   104  $ etcdctl role grant-permission myrolename --prefix=true readwrite /pub/
   105  ```
   106  
   107  To see what's granted, we can look at the role at any time:
   108  
   109  ```
   110  $ etcdctl role get myrolename
   111  ```
   112  
   113  Revocation of permissions is done the same logical way:
   114  
   115  ```
   116  $ etcdctl role revoke-permission myrolename /foo/bar
   117  ```
   118  
   119  As is removing a role entirely:
   120  
   121  ```
   122  $ etcdctl role remove myrolename
   123  ```
   124  
   125  ## Enabling authentication
   126  
   127  The minimal steps to enabling auth are as follows. The administrator can set up users and roles before or after enabling authentication, as a matter of preference.
   128  
   129  Make sure the root user is created:
   130  
   131  ```
   132  $ etcdctl user add root
   133  Password of root:
   134  ```
   135  
   136  Enable authentication:
   137  
   138  ```
   139  $ etcdctl auth enable
   140  ```
   141  
   142  After this, etcd is running with authentication enabled. To disable it for any reason, use the reciprocal command:
   143  
   144  ```
   145  $ etcdctl --user root:rootpw auth disable
   146  ```
   147  
   148  ## Using `etcdctl` to authenticate
   149  
   150  `etcdctl` supports a similar flag as `curl` for authentication.
   151  
   152  ```
   153  $ etcdctl --user user:password get foo
   154  ```
   155  
   156  The password can be taken from a prompt:
   157  
   158  ```
   159  $ etcdctl --user user get foo
   160  ```
   161  
   162  The password can also be taken from a command line flag `--password`:
   163  
   164  ```
   165  $ etcdctl --user user --password password get foo
   166  ```
   167  
   168  
   169  Otherwise, all `etcdctl` commands remain the same. Users and roles can still be created and modified, but require authentication by a user with the root role.
   170  
   171  ## Using TLS Common Name
   172  As of version v3.2 if an etcd server is launched with the option `--client-cert-auth=true`, the field of Common Name (CN) in the client's TLS cert will be used as an etcd user. In this case, the common name authenticates the user and the client does not need a password. Note that if both of 1. `--client-cert-auth=true` is passed and CN is provided by the client, and 2. username and password are provided by the client, the username and password based authentication is prioritized. Note that this feature cannot be used with gRPC-proxy and gRPC-gateway. This is because gRPC-proxy terminates TLS from its client so all the clients share a cert of the proxy. gRPC-gateway uses a TLS connection internally for transforming HTTP request to gRPC request so it shares the same limitation. Therefore the clients cannot provide their CN to the server correctly. gRPC-proxy will cause an error and stop if a given cert has non empty CN. gRPC-proxy returns an error which indicates that the client has an non empty CN in its cert.
   173  
   174  As of version v3.3 if an etcd server is launched with the option `--peer-cert-allowed-cn` filtering of CN inter-peer connections is enabled.  Nodes can only join the etcd cluster if their CN match the allowed one.
   175  See [etcd security page](https://github.com/etcd-io/etcd/blob/master/Documentation/op-guide/security.md) for more details.
   176  
   177  ## Notes on password strength
   178  `etcdctl` command line interface and etcd API don't check a strength (length, coexistence of numbers and alphabets, etc) of the password during creating a new user or updating password of an existing user. An administrator needs to care about a requirement of password strength by themselves.