From: Thomas Kriechbaumer <thomas@kriechbaumer.name>
Date: Thu, 16 May 2019 17:33:03 +0000 (+0200)
Subject: docs: improve rgw ldap auth options
X-Git-Tag: v15.1.0~1911^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=7ab44cb2135eb086a9de1df1075c893b2c487e2a;p=ceph.git

docs: improve rgw ldap auth options

Signed-off-by: Thomas Kriechbaumer <thomas@kriechbaumer.name>
---

diff --git a/doc/radosgw/config-ref.rst b/doc/radosgw/config-ref.rst
index 18402fc61d2e..937f917030cc 100644
--- a/doc/radosgw/config-ref.rst
+++ b/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
 ==============
diff --git a/doc/radosgw/ldap-auth.rst b/doc/radosgw/ldap-auth.rst
index be854c1e5197..1775091d0ead 100644
--- a/doc/radosgw/ldap-auth.rst
+++ b/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.
@@ -125,14 +131,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!