Merge pull request ceph#28157 from Kriechi/docs-rgw-ldap

docs: improve rgw ldap auth options

doc/radosgw/config-ref.rst

@@ -500,6 +500,15 @@ file under each ``[client.radosgw.{instance-name}]`` instance.
    ``rgw md log max shards`` should not be changed after sync has
    started.
 
+S3 Settings
+===========
+
+``rgw s3 auth use ldap``
+
+:Description: Should S3 authentication use LDAP.
+:Type: Boolean
+:Default: ``false``
+
 
 Swift Settings
 ==============

doc/radosgw/ldap-auth.rst

@@ -14,13 +14,18 @@ search filter is constructed with the user name. The Ceph Object Gateway uses
 the configured service account to search the directory for a matching entry. If
 an entry is found, the Ceph Object Gateway attempts to bind to the found
 distinguished name with the password from the token. If the credentials are
-valid, the bind will succeed, and the Ceph Object Gateway will grant access.
+valid, the bind will succeed, and the Ceph Object Gateway will grant access and
+radosgw-user will be created with the provided username.
 
 You can limit the allowed users by setting the base for the search to a
 specific organizational unit or by specifying a custom search filter, for
 example requiring specific group membership, custom object classes, or
 attributes.
 
+The LDAP credentials must be available on the server to perform the LDAP
+authentication. Make sure to set the ``rgw`` log level low enough to hide the
+base-64-encoded credentials / access tokens.
+
 Requirements
 ============
 
@@ -53,6 +58,7 @@ Configuring the Ceph Object Gateway to use LDAP authentication
 The following parameters in the Ceph configuration file are related to the LDAP
 authentication:
 
+- ``rgw_s3_auth_use_ldap``: Set this to ``true`` to enable S3 authentication with LDAP
 - ``rgw_ldap_uri``:  Specifies the LDAP server to use. Make sure to use the
   ``ldaps://<fqdn>:<port>`` parameter to not transmit clear text credentials
   over the wire.
@@ -126,14 +132,36 @@ access token.
 
   # export RGW_ACCESS_KEY_ID="<username>"
   # export RGW_SECRET_ACCESS_KEY="<password>"
-  # radosgw-token --encode --ttype=ldap
-
-.. note:: For Active Directroy use the ``--ttype=ad`` parameter.
+  # radosgw-token --encode
 
 .. important:: The access token is a base-64 encoded JSON struct and contains
                the LDAP credentials as a clear text.
 
-Testing access
-==============
+Alternatively, users can also generate the token manually by base-64-encoding
+this JSON snippet, if they do not have the ``radosgw-token`` tool installed.
+
+::
+
+  {
+    "RGW_TOKEN": {
+      "version": 1,
+      "type": "ldap",
+      "id": "your_username",
+      "key": "your_clear_text_password_here"
+    }
+  }
+
+Using the access token
+======================
 
-Use your favorite S3 client and specify the token as the access key.
+Use your favorite S3 client and specify the token as the access key in your
+client or environment variables.
+
+::
+
+  # export AWS_ACCESS_KEY_ID=<base64-encoded token generated by radosgw-token>
+  # export AWS_SECRET_ACCESS_KEY="" # define this with an empty string, otherwise tools might complain about missing env variables.
+
+.. important:: The access token is a base-64 encoded JSON struct and contains
+               the LDAP credentials as a clear text. DO NOT share it unless
+               you want to share your clear text password!