.. _authentication: Authentication ============== Default ------- By default, pulp authenticates each request with a username and password against its own user database. Requests can also authenticate with a client-side SSL certificate that was provided by pulp's login feature. Apache Preauthentication ------------------------ If other forms of authentication are desired, authentication can be delegated to apache, which comes with a variety of authentication plugins that are well-documented and feature-rich. In order for users to then be authorized for any operation, they must have already been added to the Pulp user database using the ``pulp-admin auth user`` commands. Once an apache authorization module is configured, pulp will read and trust the ``REMOTE_USER`` variable from apache. .. note:: Enabling apache preauthentication as described below *disables* authorization against the built-in user database, so you will not be able to authenticate as ``admin`` after you have enabled it. It's important that you configure a user in the ``super-users`` role *before* you enable apache preauthentication. Pulp's native (and deprecated) LDAP authentication is also disabled; OAuth will continue to work. Pulp's apache config file (``/etc/httpd/conf.d/pulp.conf``) contains an example of how to configure an apache auth module. The examples below demonstrate two different approaches. LDAP Whole-API Example ~~~~~~~~~~~~~~~~~~~~~~ To set up apache authentication for the entire REST API, modify the ```` stanza in ``/etc/httpd/conf.d/pulp.conf`` to resemble the following:: # pass everything that isn't a Basic auth request through to Pulp SetEnvIfNoCase ^Authorization$ "Basic.*" USE_APACHE_AUTH=1 Order allow,deny Allow from env=!USE_APACHE_AUTH Satisfy Any # configure basic auth AuthType basic AuthBasicProvider ldap AuthName "Pulp" AuthLDAPURL "ldaps://ad.example.com?sAMAccountName" AuthLDAPBindDN "cn=pulp,..." AuthLDAPBindPassword "adpassword" AuthLDAPRemoteUserAttribute sAMAccountName AuthzLDAPAuthoritative On Require valid-user # Standard Pulp REST API configuration goes here... Note that this *requires* LDAP authentication for the initial login, and *allows* either LDAP or Pulp certificate authentication on the entire API. Basic Auth Login Example ~~~~~~~~~~~~~~~~~~~~~~~~ Many deployments will only use a third-party authentication source for the login call, and then use pulp's certificate-based auth for successive calls. You are responsible for ensuring that a user gets created in pulp prior to any login attempt. Pulp does not support auto-creation of users that exist in your external source. Below is a "basic" example that works for demos, but a stronger mechanism is recommended. :: AuthType Basic AuthName "Pulp Login" AuthUserFile /var/lib/pulp/.htaccess Require valid-user For this basic-auth example, the ``.htaccess`` file must then be created using the ``htpasswd`` command. Note that this *requires* Apache authentication for the initial login, and also *requires* Pulp certificate authentication on the entire API. LDAP ---- .. deprecated:: 2.4 Please use apache's mod_authnz_ldap to provide preauthentication per instructions above. Pulp supports LDAP authentication by configuring the ``[ldap]`` section in ``server.conf``. An LDAP user who logs in for the first time will have a local account automatically created in the Pulp database. The following options are supported: * ``enabled``: Boolean; controls whether or not LDAP authentication is enabled. Default: false. * ``uri``: URL of LDAP server. Default: ``ldap://localhost`` * ``base``: Location in the directory from which the LDAP search begins. Default: ``dc=localhost`` * ``tls``: Boolean; controls whether or not to use TLS security. Default: false. * ``default_role``: Role ID to assign LDAP users to by default. This role must first be created on the Pulp server. If ``default_role`` is not set or doesn't exist, LDAP users are given same default permissions as local users. * ``filter``: LDAP filter to limit the LDAP users who can authenticate to Pulp. For example: .. code-block:: ini [ldap] enabled = true uri = ldap://ldap.example.com base = ou=People,dc=example,dc=com tls = true default_role = ldap-users filter = (gidNumber=200) .. _oauth-config: OAuth ----- .. deprecated:: 2.4.0 OAuth support will be removed in a future release of Pulp. Please do not write new code that uses OAuth against Pulp, and please find a suitable replacement if you are already using it. `OAuth `_ can be enabled by configuring the ``[oauth]`` section in ``server.conf``. In order for a user or consumer to authenticate via OAuth, they must have already been added to the Pulp user database with the ``pulp-admin auth user`` commands. The following options are supported: * ``enabled``: Boolean; controls whether OAuth authentication is enabled. Default: false * ``oauth_key``: Key to enable OAuth style authentication. Required. * ``oauth_secret``: Shared secret that can be used for OAuth style authentication. Please be sure to choose a secret that is long enough for your desired level of security. Required. For example: .. code-block:: ini [oauth] enabled = true oauth_key = ab3cd9j4ks73hf7g oauth_secret = xyz4992k83j47x0bBoo8fue3yohneepo .. warning:: Do not use the key or secret given in the above example. It is important that you use unique and secret values for these configuration items.