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 and
  18 radosgw-user will be created with the provided username.
  19
  20 You can limit the allowed users by setting the base for the search to a
  21 specific organizational unit or by specifying a custom search filter, for
  22 example requiring specific group membership, custom object classes, or
  23 attributes.
  24
  25 The LDAP credentials must be available on the server to perform the LDAP
  26 authentication. Make sure to set the ``rgw`` log level low enough to hide the
  27 base-64-encoded credentials / access tokens.
  28
  29 Requirements
  30 ============
  31
  32 - **LDAP or Active Directory:** A running LDAP instance accessible by the Ceph
  33   Object Gateway
  34 - **Service account:** LDAP credentials to be used by the Ceph Object Gateway
  35   with search permissions
  36 - **User account:** At least one user account in the LDAP directory
  37 - **Do not overlap LDAP and local users:** You should not use the same user
  38   names for local users and for users being authenticated by using LDAP. The
  39   Ceph Object Gateway cannot distinguish them and it treats them as the same
  40   user.
  41
  42 Sanity checks
  43 =============
  44
  45 Use the ``ldapsearch`` utility to verify the service account or the LDAP connection:
  46
  47 ::
  48
  49   # ldapsearch -x -D "uid=ceph,ou=system,dc=example,dc=com" -W \
  50   -H ldaps://example.com -b "ou=users,dc=example,dc=com" 'uid=*' dn
  51
  52 .. note:: Make sure to use the same LDAP parameters like in the Ceph configuration file to
  53           eliminate possible problems.
  54
  55 Configuring the Ceph Object Gateway to use LDAP authentication
  56 ==============================================================
  57
  58 The following parameters in the Ceph configuration file are related to the LDAP
  59 authentication:
  60
  61 - ``rgw_s3_auth_use_ldap``: Set this to ``true`` to enable S3 authentication with LDAP
  62 - ``rgw_ldap_uri``:  Specifies the LDAP server to use. Make sure to use the
  63   ``ldaps://<fqdn>:<port>`` parameter to not transmit clear text credentials
  64   over the wire.
  65 - ``rgw_ldap_binddn``: The Distinguished Name (DN) of the service account used
  66   by the Ceph Object Gateway
  67 - ``rgw_ldap_secret``: Path to file containing credentials for ``rgw_ldap_binddn``
  68 - ``rgw_ldap_searchdn``: Specifies the base in the directory information tree
  69   for searching users. This might be your users organizational unit or some
  70   more specific Organizational Unit (OU).
  71 - ``rgw_ldap_dnattr``: The attribute being used in the constructed search
  72   filter to match a username. Depending on your Directory Information Tree
  73   (DIT) this would probably be ``uid`` or ``cn``. The generated filter string
  74   will be, e.g., ``cn=some_username``.
  75 - ``rgw_ldap_searchfilter``: If not specified, the Ceph Object Gateway
  76   automatically constructs the search filter with the ``rgw_ldap_dnattr``
  77   setting. Use this parameter to narrow the list of allowed users in very
  78   flexible ways. Consult the *Using a custom search filter to limit user access
  79   section* for details
  80
  81 Using a custom search filter to limit user access
  82 =================================================
  83
  84 There are two ways to use the ``rgw_search_filter`` parameter:
  85
  86 Specifying a partial filter to further limit the constructed search filter
  87 --------------------------------------------------------------------------
  88
  89 An example for a partial filter:
  90
  91 ::
  92
  93   "objectclass=inetorgperson"
  94
  95 The Ceph Object Gateway will generate the search filter as usual with the
  96 user name from the token and the value of ``rgw_ldap_dnattr``. The constructed
  97 filter is then combined with the partial filter from the ``rgw_search_filter``
  98 attribute. Depending on the user name and the settings the final search filter
  99 might become:
 100
 101 ::
 102
 103   "(&(uid=hari)(objectclass=inetorgperson))"
 104
 105 So user ``hari`` will only be granted access if he is found in the LDAP
 106 directory, has an object class of ``inetorgperson``, and did specify a valid
 107 password.
 108
 109 Specifying a complete filter
 110 ----------------------------
 111
 112 A complete filter must contain a ``@USERNAME@`` token which will be substituted
 113 with the user name during the authentication attempt. The ``rgw_ldap_dnattr``
 114 parameter is not used anymore in this case. For example, to limit valid users
 115 to a specific group, use the following filter:
 116
 117 ::
 118
 119   "(&(uid=@USERNAME@)(memberOf=cn=ceph-users,ou=groups,dc=mycompany,dc=com))"
 120
 121 .. note:: Using the ``memberOf`` attribute in LDAP searches requires server side
 122           support from you specific LDAP server implementation.
 123
 124 Generating an access token for LDAP authentication
 125 ==================================================
 126
 127 The ``radosgw-token`` utility generates the access token based on the LDAP
 128 user name and password. It will output a base-64 encoded string which is the
 129 access token.
 130
 131 ::
 132
 133   # export RGW_ACCESS_KEY_ID="<username>"
 134   # export RGW_SECRET_ACCESS_KEY="<password>"
 135   # radosgw-token --encode
 136
 137 .. important:: The access token is a base-64 encoded JSON struct and contains
 138                the LDAP credentials as a clear text.
 139
 140 Alternatively, users can also generate the token manually by base-64-encoding
 141 this JSON snippet, if they do not have the ``radosgw-token`` tool installed.
 142
 143 ::
 144
 145   {
 146     "RGW_TOKEN": {
 147       "version": 1,
 148       "type": "ldap",
 149       "id": "your_username",
 150       "key": "your_clear_text_password_here"
 151     }
 152   }
 153
 154 Using the access token
 155 ======================
 156
 157 Use your favorite S3 client and specify the token as the access key in your
 158 client or environment variables.
 159
 160 ::
 161
 162   # export AWS_ACCESS_KEY_ID=<base64-encoded token generated by radosgw-token>
 163   # export AWS_SECRET_ACCESS_KEY="" # define this with an empty string, otherwise tools might complain about missing env variables.
 164
 165 .. important:: The access token is a base-64 encoded JSON struct and contains
 166                the LDAP credentials as a clear text. DO NOT share it unless
 167                you want to share your clear text password!