rlx-auth(3) -- authentication commands ====================================== ## SYNOPSIS Commands for authentication, user management and inspecting information about current sessions. ## COMMANDS Any command that accepts a *url* option will also accept an explicit alias reference, if no *url* option is specified the current server is used. The `login` command is provided to explicitly login to a server, however, whenever a 401 response is received you will be prompted for authentication credentials. * `login [url] [username]`: Authenticate to a server using a cookie-based session login. If *username* is specified it is used and you will only need to enter the password to authenticate. If authentication fails from an attempt to login an error is printed, if there are three successive failed attempts to authenticate the login command aborts and you will either need to invoke the `login` command again or the command that triggered the 401 response. If authentication is successful and no server is selected the current server is set to the server used for authentication. * `whoami [url]`: Print the username of the currently logged in user for *url*, if *url* is not specified the currently selected server is used. If no authentication information is available (not logged in) the name *anonymous* is printed. * `session [url]`: Print the document representing the current session or the session for *url*. * `logout [url]`: Logout out of the server specified by *url*, if *url* is not specified the currently selected server is used. If you logout from a server which is currently selected then the selected context is cleared and you will need to use the `cd` command to set the selected server. * `auth ls`: Print a list of URLs representing the currently authenticated usernames and servers. * `auth require [valid]`: Alias used to set the `require_valid_user` key of the `couch_httpd_auth` config section, the value for *valid* must be either `true` or `false`. ## ADMIN COMMANDS Commands for managing server administrators. * `admin add [username] [url]`: Add a server admin, *username* is required. You will be prompted to enter (and confirm) the password for the new admin. * `admin rm [username] [url]`: Delete a server admin, *username* is required. Confirmation is required and if you are authenticated as the *username* being deleted an additional warning is printed. * `admin ls [url]`: List server admins, equivalent to `config get admins`. * `admin party [url]`: Delete all administrators for a server effectively reverting to admin party mode. This command prompts for confirmation and retrieves a list of the existing administrators, if no administrators exist the command is aborted. If the server has administrators configured then the list of administrators is printed along with a final confirmation to proceed. This command is provided for testing purposes and should be treated with extreme caution. ## USER COMMANDS Commands for managing users and permissions, requires admin privileges (or a server running in admin party mode). When necessary these commands will fetch the configured database name used for storing users and perform a head request to verify the database exists prior to executing the command. Do not specify the namespace *org.couchdb.user* for commands that accept a *username*. * `user db`: Print the name of the database used for authentication. * `user ns`: Print the current value of the namespace used for user documents. If the `userns` setting is `false` indicating no namespace is in use then nothing is printed. * `user ls`: List all documents in the users database (including design documents). * `user add [username] [role...]`: Add a user to the users database. You will be prompted to enter a password (and confirm the password) when creating a new user. If one or more *role* options are specified the user template has the roles array propagated. * `user edit [username]`: Open an existing user document in the editor, if the document is saved it is sent to the server. * `user rm [username]`: Delete a user from the users database. ## SECURITY COMMANDS Commands for inspecting and modifying the security object for specific databases. If no *database* is specified the currently selected database is used, if no *url* is specified the currently selected server is used. * `security [database] [url]`: Print the security object for *database*. * `security edit [database] [url]`: Edit the security object for *database*. * `security add [database] [url]`: Create a security object for *database* from a template, this should be used to create a new security object when there is no existing security object for a database. If the existing security object is not the empty object ({}) this command will defer to `security edit`. * `security rm [database] [url]`: Deletes all administrators and members from *database* by setting the security object to the empty object ({}). You will be prompted for confirmation before this command sends the request to the server. ## PASSWORDS The `passwd` command may be used to change the password for a user. The rules for this command are as follows: * The user executing the command must be authenticated. * Any user may change their own password by invoking `passwd` with no options. * Administrators may change their own password and any users password but are not allowed to change the password of other administrators. * When setting an administrator password if a user document exists with the same username it is also assigned the new password. * When a password is changed successfully for the authenticated user the `logout` and `login` commands are executed to re-authenticate the current session with the updated password. Note that even though administrators may not change the password of other administrators it is still possible for an administrator to deny access to other administrators using the `admin rm` command. * `passwd [username]`: Sets the password for *username*, if *username* is not specified this command sets the password for the currently authenticated user. A server must be selected otherwise an error is printed, be sure you are operating on the correct server (run `pwd`) before using this command. ## SECURITY This section outlines some common security concerns that you should be aware of before using rlx(1). ### User Documents When creating a new user you are prompted for the password and it is written to the editor via stdin (but using a temporary file). However, when the file is saved by the editor it is written to disc with the password in plain text. So, immediately after either the `user add` or `user edit` commands are executed both the temporary file and any saved document are deleted. Note that in the case of the `edit` command the password is hashed by couchdb so it is not in plain text form. ### Backup & Swap Files Normally the `vim` editor will be configured to use backup and swap files. By default rlx(1) is configured to disable this behaviour so that documents containing sensitive information are not saved to disc. See the `EDITOR` section of rlx(1) for more information. ### User Input Passwords are captured using readline in silent mode so that characters are not printed to the screen. In addition, password prompts do not create an entry in the command line history file. ### Curl Options Options passed to curl(1) are sent via stdin using the `--config` option so that sensitive information is not available to commands such as `ps`. ### Secure Transport Layer If you are communicating with a server over plain HTTP then sensitive information (such as passwords) are susceptible to man in the middle attacks, if you are communicating over a network then you should ensure the server is running over HTTPS to mitigate this attack vector. ## FILES Cookies used for session authentication are stored in a file name `cookie.txt` within a temporary directory for the process. ## BUGS **rlx** is written in bash and depends upon `bash >= 4.2`. ## COPYRIGHT **rlx** is copyright (c) 2013 muji ## SEE ALSO rlx(1), couchdb(3), rlx-alias(3)