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]