# 基于角色的访问控制(TBD) ## Overview 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. ## Special users and roles There is one special user, `root`, and one special role, `root`. ### User `root` 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. ### Role `root` 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. ## Working with users The `user` subcommand for `etcdctl` handles all things having to do with user accounts. A listing of users can be found with: ``` $ etcdctl user list ``` Creating a user is as easy as ``` $ etcdctl user add myusername ``` 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. Roles can be granted and revoked for a user with: ``` $ etcdctl user grant-role myusername foo $ etcdctl user revoke-role myusername bar ``` The user's settings can be inspected with: ``` $ etcdctl user get myusername ``` And the password for a user can be changed with ``` $ etcdctl user passwd myusername ``` 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. Delete an account with: ``` $ etcdctl user delete myusername ``` ## Working with roles The `role` subcommand for `etcdctl` handles all things having to do with access controls for particular roles, as were granted to individual users. List roles with: ``` $ etcdctl role list ``` Create a new role with: ``` $ etcdctl role add myrolename ``` A role has no password; it merely defines a new set of access rights. Roles are granted access to a single key or a range of keys. 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. Access can be granted as either read, write, or both, as in the following examples: ``` # Give read access to a key /foo $ etcdctl role grant-permission myrolename read /foo # Give read access to keys with a prefix /foo/. The prefix is equal to the range [/foo/, /foo0) $ etcdctl role grant-permission myrolename --prefix=true read /foo/ # Give write-only access to the key at /foo/bar $ etcdctl role grant-permission myrolename write /foo/bar # Give full access to keys in a range of [key1, key5) $ etcdctl role grant-permission myrolename readwrite key1 key5 # Give full access to keys with a prefix /pub/ $ etcdctl role grant-permission myrolename --prefix=true readwrite /pub/ ``` To see what's granted, we can look at the role at any time: ``` $ etcdctl role get myrolename ``` Revocation of permissions is done the same logical way: ``` $ etcdctl role revoke-permission myrolename /foo/bar ``` As is removing a role entirely: ``` $ etcdctl role remove myrolename ``` ## Enabling authentication 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. Make sure the root user is created: ``` $ etcdctl user add root Password of root: ``` Enable authentication: ``` $ etcdctl auth enable ``` After this, etcd is running with authentication enabled. To disable it for any reason, use the reciprocal command: ``` $ etcdctl --user root:rootpw auth disable ``` ## Using `etcdctl` to authenticate `etcdctl` supports a similar flag as `curl` for authentication. ``` $ etcdctl --user user:password get foo ``` The password can be taken from a prompt: ``` $ etcdctl --user user get foo ``` 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. ## Using TLS Common Name 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doczhcn.gitbook.io/etcd/index/index-1/authentication.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.