Authentication ============== This guide covers basic authentication and authorization in the Pulp Platform. Basic Authentication of Users ----------------------------- All pulp-admin commands accept username and password to capture authentication credentials. :: $ pulp-admin --help Usage: pulp-admin [options] Options: -h, --help show this help message and exit -u USERNAME, --username=USERNAME username for the Pulp server; if used will bypass the stored certificate and override a username specified in ~/.pulp/admin.conf -p PASSWORD, --password=PASSWORD password for the Pulp server; must be used with --username. if used will bypass the stored certificate and override a password specified in ~/.pulp/admin.conf --config=CONFIG absolute path to the configuration file --map prints a map of the CLI sections and commands -v enables verbose output; use twice for increased verbosity with debug information Pulp Admin client allows the user to specify username and password credentials in the user's local admin.conf ``~/.pulp/admin.conf``. Using the conf file avoids having to pass user credentials repeatedly using the command line. Also reading the password from a file that can only be read by certain users is more secure because it cannot be shown by listing the system processes. :: # Add the following snippet to ``~/.pulp/admin.conf`` [auth] username: admin password: admin # This enables the user to run pulp-admin commands without providing a username # and password using the command line $ pulp-admin repo list +----------------------------------------------------------------------+ Repositories +----------------------------------------------------------------------+ pulp-admin searches for a username and password to use in the following order: - credentials specified from the command line. - credentials set in the user's ``~/.pulp/admin.conf``. Pulp Server installation comes with one default user created with admin level privileges. Username and password for this user can be configured in ``/etc/pulp/server.conf`` at the time of installation. Below is an example of basic authentication of users based on their username and password when running a pulp-admin command. :: $ pulp-admin repo list Enter password: +----------------------------------------------------------------------+ Repositories +----------------------------------------------------------------------+ Note that username and password are parameters to the ``pulp-admin`` command, not the sub-command, like ``repo list`` in this case. You can also pass the password parameter on the command line with ``--password`` argument, but this is not a recommended method. Users should use interactive password as a preferred method. Rather than specifying the credentials on each call to pulp-admin, a user can log in to the Pulp server. Logging in stores a user credentials certificate at ``~/.pulp/user-cert.pem``. :: $ pulp-admin login -u admin Enter password: Successfully logged in. Session certificate will expire at Dec 6 21:47:33 2012 GMT. Subsequent commands to pulp-admin will no longer require the username-password arguments and will instead use the user certificate. The user can be logged out by using the ``pulp-admin logout`` command. :: $ pulp-admin logout Session certificate successfully removed. Layout of Auth Section ---------------------- The root level ``auth`` section contains sub-sections to create and manage Pulp users, roles and their permissions for various resources. :: $ pulp-admin auth Usage: pulp-admin auth [SUB_SECTION, ..] COMMAND Description: user, role and permission commands Available Sections: permission - manage granting, revoking and listing permissions for resources role - manage user roles user - manage users Users ----- Users can be created to perform various administrative tasks on the Pulp Server. You can configure them with either admin level access or limited access to a few resources on the server. :: $ pulp-admin auth user --help Usage: pulp-admin user [SUB_SECTION, ..] COMMAND Description: manage users Available Commands: create - creates a user delete - deletes a user list - lists summary of users registered to the Pulp server search - search items while optionally specifying sort, limit, skip, and requested fields update - changes metadata of an existing user Here is an example of creating and updating a user: :: $ pulp-admin auth user create --login test-user Enter password for user [test-user] : Re-enter password for user [test-user]: User [test-user] successfully created If you intend to update the password for a user, you can use ``-p`` flag as shown in the example below to be prompted for a new password. :: $ pulp-admin auth user update --login test-user --name "Test User" -p Enter new password for user [test-user] : Re-enter new password for user [test-user]: User [test-user] successfully updated You can also pass it on the command line with ``--password`` argument, but this method is just to provide a simpler way for scripting and is not recommended. Users should use interactive password update as a preferred method. The ``user list`` command lists a summary of all users. It also accepts arguments to list all the details or specific fields for users. :: $ pulp-admin auth user list --details +----------------------------------------------------------------------+ Users +----------------------------------------------------------------------+ Login: admin Name: admin Roles: super-users Login: test-user Name: test-user Roles: :: $ pulp-admin auth user list --fields roles +----------------------------------------------------------------------+ Users +----------------------------------------------------------------------+ Login: admin Roles: super-users Login: test-user Roles: Users can be removed from the Pulp server using the ``user delete`` command. :: $ pulp-admin auth user delete --login test-user User [test-user] successfully deleted Users belonging to the ``super-users`` role can be deleted as well, as long as there is at least one such user remaining in the system. :: $ pulp-admin auth user delete --login admin The server indicated one or more values were incorrect. The server provided the following error message: The last superuser [admin] cannot be deleted Permissions ----------- Permissions to various resources can be accessed or manipulated using ``pulp-admin auth permission`` commands. There are 5 types of permissions - CREATE, READ, UPDATE, DELETE and EXECUTE. Permissions are granted and revoked from a resource which is essentially a REST API path with the ``/pulp/api`` prefix removed. Here are a few examples of accessing and manipulation permissions: :: $ pulp-admin auth permission list --resource / +----------------------------------------------------------------------+ Permissions for / +----------------------------------------------------------------------+ Admin: CREATE, READ, UPDATE, DELETE, EXECUTE The following command will give permissions to create, read and update repositories to ``test-user``. :: $ pulp-admin auth permission grant --resource /v2/repositories/ --login test-user -o create -o update -o read Permissions [/v2/repositories/ : ['CREATE', 'UPDATE', 'READ']] successfully granted to user [test-user] :: $ pulp-admin auth permission list --resource /v2/repositories/ +----------------------------------------------------------------------+ Permissions for /repositories +----------------------------------------------------------------------+ Test-user: CREATE, UPDATE, READ The following command will revoke permissions to create and update repositories from ``test-user``. :: $ pulp-admin auth permission revoke --resource /v2/repositories/ --login test-user -o create -o update Permissions [/v2/repositories/ : ['CREATE', 'UPDATE']] successfully revoked from user [test-user] .. note:: The ``/v2`` prefix and the trailing ``/`` are always present in a resource name for permission commands. Roles ----- In order to efficiently administer permissions, Pulp uses the notion of roles to enable an administrator to grant and revoke permission on a resource to a group of users instead of individually. The ``pulp-admin auth role`` command provides the ability to list the currently defined roles, create/delete roles, and manage user membership in a role. Pulp installation comes with a default ``super-users`` role with admin level privileges, and the default admin user belongs to this role. The ``role list`` command is used to list the current roles. :: $ pulp-admin auth role list +----------------------------------------------------------------------+ Roles +----------------------------------------------------------------------+ Id: super-users Users: admin A role can be created and deleted by specifying a role id. :: $ pulp-admin auth role create --role-id consumer-admin Role [consumer-admin] successfully created $ pulp-admin auth role delete --role-id consumer-admin Role [consumer-admin] successfully deleted A user can be added and removed from a role using ``role user add`` and ``role user remove`` commands respectively. Note that both the user and the role should exist on the pulp server. :: $ pulp-admin auth role user add --role-id super-users --login test-user User [test-user] successfully added to role [super-users] $ pulp-admin auth role user remove --role-id super-users --login test-user User [test-user] successfully removed from role [super-users] Permissions can be granted and revoked from roles just like users. In this case all the users belonging to the given role will inherit these permissions. :: $ pulp-admin auth permission grant --resource /v2/repositories/ --role-id test-role -o read Permissions [/v2/repositories/ : ['READ']] successfully granted to role [test-role] $ pulp-admin auth permission revoke --resource /v2/repositories/ --role-id test-role -o read Permissions [/v2/repositories/ : ['READ']] successfully revoked from role [test-role]