docs: describe ROPC flow in place of password authentication

nejch · JohnVillalovos · commit 91c17b704f51 · 2022-07-04T22:40:14.000-07:00
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
@@ -9,6 +9,15 @@ python-gitlab only supports GitLab API v4.
 
 To connect to GitLab.com or another GitLab instance, create a ``gitlab.Gitlab`` object:
 
+.. hint::
+
+   You can use different types of tokens for authenticated requests against the GitLab API.
+   You will most likely want to use a resource (project/group) access token or a personal
+   access token.
+
+   For the full list of available options and how to obtain these tokens, please see
+   https://docs.gitlab.com/ee/api/index.html#authentication.
+
 .. code-block:: python
 
    import gitlab
@@ -37,9 +46,8 @@ To connect to GitLab.com or another GitLab instance, create a ``gitlab.Gitlab``
    # Define your own custom user agent for requests
    gl = gitlab.Gitlab('https://gitlab.example.com', user_agent='my-package/1.0.0')
 
-   # make an API request to create the gl.user object. This is mandatory if you
-   # use the username/password authentication - not required for token authentication,
-   # and will not work with job tokens.
+   # make an API request to create the gl.user object. This is not required but may be useful
+   # to validate your token authentication. Note that this will not work with job tokens.
    gl.auth()
 
 You can also use configuration files to create ``gitlab.Gitlab`` objects:
@@ -68,18 +76,16 @@ configuration files.
 Note on password authentication
 -------------------------------
 
-The ``/session`` API endpoint used for username/password authentication has
-been removed from GitLab in version 10.2, and is not available on gitlab.com
-anymore. Personal token authentication is the preferred authentication method.
+GitLab has long removed password-based basic authentication. You can currently still use the
+`resource owner password credentials <https://docs.gitlab.com/ee/api/oauth2.html#resource-owner-password-credentials-flow>`_
+flow to obtain an OAuth token.
 
-If you need username/password authentication, you can use cookie-based
-authentication. You can use the web UI form to authenticate, retrieve cookies,
-and then use a custom ``requests.Session`` object to connect to the GitLab API.
-The following code snippet demonstrates how to automate this:
-https://gist.github.com/gpocentek/bd4c3fbf8a6ce226ebddc4aad6b46c0a.
+However, we do not recommend this as it will not work with 2FA enabled, and GitLab is removing
+ROPC-based flows without client IDs in a future release. We recommend you obtain tokens for
+automated workflows as linked above or obtain a session cookie from your browser.
 
-See `issue 380 <https://github.com/python-gitlab/python-gitlab/issues/380>`_
-for a detailed discussion.
+For a python example of password authentication using the ROPC-based OAuth2
+flow, see `this Ansible snippet <https://github.com/ansible-collections/community.general/blob/1c06e237c8100ac30d3941d5a3869a4428ba2974/plugins/module_utils/gitlab.py#L86-L92>`_.
 
 Managers
 ========
diff --git a/docs/cli-usage.rst b/docs/cli-usage.rst
@@ -176,16 +176,11 @@ We recommend that you use `Credential helpers`_ to securely store your tokens.
        to learn how to obtain a token.
    * - ``api_version``
      - GitLab API version to use. Only ``4`` is available since 1.5.0.
-   * - ``http_username``
-     - Username for optional HTTP authentication
-   * - ``http_password``
-     - Password for optional HTTP authentication
-
 
 Credential helpers
 ------------------
 
-For all configuration options that contain secrets (``http_password``,
+For all configuration options that contain secrets (for example,
 ``personal_token``, ``oauth_token``, ``job_token``), you can specify
 a helper program to retrieve the secret indicated by a ``helper:``
 prefix. This allows you to fetch values from a local keyring store
@@ -229,7 +224,7 @@ In `/path/to/helper.sh`:
 .. code-block:: bash
 
     #!/bin/bash
-    pass show path/to/password | head -n 1
+    pass show path/to/credentials | head -n 1
 
 CLI
 ===
