src/ceph/doc/radosgw/ldap-auth.rst

   1 ===================
   2 LDAP Authentication
   3 ===================
   4
   5 .. versionadded:: Jewel
   6
   7 You can delegate the Ceph Object Gateway authentication to an LDAP server.
   8
   9 How it works
  10 ============
  11
  12 The Ceph Object Gateway extracts the users LDAP credentials from a token. A
  13 search filter is constructed with the user name. The Ceph Object Gateway uses
  14 the configured service account to search the directory for a matching entry. If
  15 an entry is found, the Ceph Object Gateway attempts to bind to the found
  16 distinguished name with the password from the token. If the credentials are
  17 valid, the bind will succeed, and the Ceph Object Gateway will grant access.
  18
  19 You can limit the allowed users by setting the base for the search to a
  20 specific organizational unit or by specifying a custom search filter, for
  21 example requiring specific group membership, custom object classes, or
  22 attributes.
  23
  24 Requirements
  25 ============
  26
  27 - **LDAP or Active Directory:** A running LDAP instance accessible by the Ceph
  28   Object Gateway
  29 - **Service account:** LDAP credentials to be used by the Ceph Object Gateway
  30   with search permissions
  31 - **User account:** At least one user account in the LDAP directory
  32 - **Do not overlap LDAP and local users:** You should not use the same user
  33   names for local users and for users being authenticated by using LDAP. The
  34   Ceph Object Gateway cannot distinguish them and it treats them as the same
  35   user.
  36
  37 Sanity checks
  38 =============
  39
  40 Use the ``ldapsearch`` utility to verify the service account or the LDAP connection:
  41
  42 ::
  43
  44   # ldapsearch -x -D "uid=ceph,ou=system,dc=example,dc=com" -W \
  45   -H ldaps://example.com -b "ou=users,dc=example,dc=com" 'uid=*' dn
  46
  47 .. note:: Make sure to use the same LDAP parameters like in the Ceph configuration file to
  48           eliminate possible problems.
  49
  50 Configuring the Ceph Object Gateway to use LDAP authentication
  51 ==============================================================
  52
  53 The following parameters in the Ceph configuration file are related to the LDAP
  54 authentication:
  55
  56 - ``rgw_ldap_uri``:  Specifies the LDAP server to use. Make sure to use the
  57   ``ldaps://<fqdn>:<port>`` parameter to not transmit clear text credentials
  58   over the wire.
  59 - ``rgw_ldap_binddn``: The Distinguished Name (DN) of the service account used
  60   by the Ceph Object Gateway
  61 - ``rgw_ldap_secret``: The password for the service account
  62 - ``rgw_ldap_searchdn``: Specifies the base in the directory information tree
  63   for searching users. This might be your users organizational unit or some
  64   more specific Organizational Unit (OU).
  65 - ``rgw_ldap_dnattr``: The attribute being used in the constructed search
  66   filter to match a username. Depending on your Directory Information Tree
  67   (DIT) this would probably be ``uid`` or ``cn``.
  68 - ``rgw_search_filter``: If not specified, the Ceph Object Gateway
  69   automatically constructs the search filter with the ``rgw_ldap_dnattr``
  70   setting. Use this parameter to narrow the list of allowed users in very
  71   flexible ways. Consult the *Using a custom search filter to limit user access
  72   section* for details
  73
  74 Using a custom search filter to limit user access
  75 =================================================
  76
  77 There are two ways to use the ``rgw_search_filter`` parameter:
  78
  79 Specifying a partial filter to further limit the constructed search filter
  80 --------------------------------------------------------------------------
  81
  82 An example for a partial filter:
  83
  84 ::
  85
  86   "objectclass=inetorgperson"
  87
  88 The Ceph Object Gateway will generate the search filter as usual with the
  89 user name from the token and the value of ``rgw_ldap_dnattr``. The constructed
  90 filter is then combined with the partial filter from the ``rgw_search_filter``
  91 attribute. Depending on the user name and the settings the final search filter
  92 might become:
  93
  94 ::
  95
  96   "(&(uid=hari)(objectclass=inetorgperson))"
  97
  98 So user ``hari`` will only be granted access if he is found in the LDAP
  99 directory, has an object class of ``inetorgperson``, and did specify a valid
 100 password.
 101
 102 Specifying a complete filter
 103 ----------------------------
 104
 105 A complete filter must contain a ``USERNAME`` token which will be substituted
 106 with the user name during the authentication attempt. The ``rgw_ldap_dnattr``
 107 parameter is not used anymore in this case. For example, to limit valid users
 108 to a specific group, use the following filter:
 109
 110 ::
 111
 112   "(&(uid=USERNAME)(memberOf=cn=ceph-users,ou=groups,dc=mycompany,dc=com))"
 113
 114 .. note:: Using the ``memberOf`` attribute in LDAP searches requires server side
 115           support from you specific LDAP server implementation.
 116
 117 Generating an access token for LDAP authentication
 118 ==================================================
 119
 120 The ``radosgw-token`` utility generates the access token based on the LDAP
 121 user name and password. It will output a base-64 encoded string which is the
 122 access token.
 123
 124 ::
 125
 126   # export RGW_ACCESS_KEY_ID="<username>"
 127   # export RGW_SECRET_ACCESS_KEY="<password>"
 128   # radosgw-token --encode --ttype=ldap
 129
 130 .. note:: For Active Directroy use the ``--ttype=ad`` parameter.
 131
 132 .. important:: The access token is a base-64 encoded JSON struct and contains
 133                the LDAP credentials as a clear text.
 134
 135 Testing access
 136 ==============
 137
 138 Use your favorite S3 client and specify the token as the access key.