From 3930f5545f1e5f3e3706eedb4b023195f74b655b Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Fri, 28 May 2021 13:15:25 +0100 Subject: [PATCH] Add a topic guide for Authentication --- docs/html/topics/authentication.md | 83 ++++++++++++++++++++++++++++++ docs/html/topics/index.md | 2 + docs/html/user_guide.rst | 63 ++--------------------- 3 files changed, 88 insertions(+), 60 deletions(-) create mode 100644 docs/html/topics/authentication.md diff --git a/docs/html/topics/authentication.md b/docs/html/topics/authentication.md new file mode 100644 index 00000000000..e78aff47201 --- /dev/null +++ b/docs/html/topics/authentication.md @@ -0,0 +1,83 @@ +# Authentication + +## Basic HTTP authentication + +pip supports basic HTTP-based authentication credentials. This is done by +providing the username (and optionally password) in the URL: + +``` +https://username:password@pypi.company.com/simple +``` + +For indexes that only require single-part authentication tokens, provide the +token as the "username" and do not provide a password: + +``` +https://0123456789abcdef@pypi.company.com/simple +``` + +### Percent-encoding special characters + +```{versionaddded} 10.0 +``` + +Certain special characters are not valid in the credential part of a URL. +If the user or password part of your login credentials contain any of these +[special characters][reserved-chars], then they must be percent-encoded. As an +example, for a user with username `user` and password `he//o` accessing a +repository at `pypi.company.com/simple`, the URL with credentials would look +like: + +``` +https://user:he%2F%2Fo@pypi.company.com/simple +``` + +[reserved-chars]: https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters + +## netrc support + +pip supports loading credentials from a user's `.netrc` file. If no credentials +are part of the URL, pip will attempt to get authentication credentials for the +URL's hostname from the user's `.netrc` file. This behaviour comes from the +underlying use of {pypi}`requests`, which in turn delegates it to the +[Python standard library's `netrc` module][netrc-std-lib]. + +```{note} +As mentioned in the [standard library documentation for netrc][netrc-std-lib], +only ASCII characters are allowed in `.netrc` files. Whitespace and +non-printable characters are not allowed in passwords. +``` + +Below is an example `.netrc`, for the host `example.com`, with a user named +`daniel`, using the password `qwerty`: + +``` +machine example.com +login daniel +password qwerty +``` + +More information about the `.netrc` file format can be found in the GNU [`ftp` +man pages][netrc-docs]. + +[netrc-docs]: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html +[netrc-std-lib]: https://docs.python.org/3/library/netrc.html + +## Keyring Support + +pip supports loading credentials stored in your keyring using the +{pypi}`keyring` library. + +```bash +$ pip install keyring # install keyring from PyPI +$ echo "your-password" | keyring set pypi.company.com your-username +$ pip install your-package --index-url https://pypi.company.com/ +``` + +Note that `keyring` (the Python package) needs to be installed separately from +pip. This can create a bootstrapping issue if you need the credentials stored in +the keyring to download and install keyring. + +It is, thus, expected that users that wish to use pip's keyring support have +some mechanism for downloading and installing {pypi}`keyring` in their Python +environment. diff --git a/docs/html/topics/index.md b/docs/html/topics/index.md index b4f984bc756..6e815ebc603 100644 --- a/docs/html/topics/index.md +++ b/docs/html/topics/index.md @@ -9,4 +9,6 @@ This section of the documentation is currently being fleshed out. See ```{toctree} :maxdepth: 1 + +authentication ``` diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 900ad503416..a36bc92689b 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -63,72 +63,17 @@ For more information and examples, see the :ref:`pip install` reference. Basic Authentication Credentials ================================ -pip supports basic authentication credentials. Basically, in the URL there is -a username and password separated by ``:``. - -``https://[username[:password]@]pypi.company.com/simple`` - -Certain special characters are not valid in the authentication part of URLs. -If the user or password part of your login credentials contain any of the -special characters -`here `_ -then they must be percent-encoded. For example, for a -user with username "user" and password "he//o" accessing a repository at -pypi.company.com, the index URL with credentials would look like: - -``https://user:he%2F%2Fo@pypi.company.com`` - -Support for percent-encoded authentication in index URLs was added in pip 10.0.0 -(in `#3236 `_). Users that must use authentication -for their Python repository on systems with older pip versions should make the latest -get-pip.py available in their environment to bootstrap pip to a recent-enough version. - -For indexes that only require single-part authentication tokens, provide the token -as the "username" and do not provide a password, for example - - -``https://0123456789abcdef@pypi.company.com`` - +This is now covered in {doc}`topics/authentication`. netrc Support ------------- -If no credentials are part of the URL, pip will attempt to get authentication credentials -for the URL’s hostname from the user’s .netrc file. This behaviour comes from the underlying -use of `requests`_ which in turn delegates it to the `Python standard library`_. - -The .netrc file contains login and initialization information used by the auto-login process. -It resides in the user's home directory. The .netrc file format is simple. You specify lines -with a machine name and follow that with lines for the login and password that are -associated with that machine. Machine name is the hostname in your URL. - -An example .netrc for the host example.com with a user named 'daniel', using the password -'qwerty' would look like: - -.. code-block:: shell - - machine example.com - login daniel - password qwerty - -As mentioned in the `standard library docs `_, -only ASCII characters are allowed. Whitespace and non-printable characters are not allowed in passwords. - +This is now covered in {doc}`topics/authentication`. Keyring Support --------------- -pip also supports credentials stored in your keyring using the `keyring`_ -library. Note that ``keyring`` will need to be installed separately, as pip -does not come with it included. - -.. code-block:: shell - - pip install keyring - echo your-password | keyring set pypi.company.com your-username - pip install your-package --index-url https://pypi.company.com/ - -.. _keyring: https://pypi.org/project/keyring/ - +This is now covered in {doc}`topics/authentication`. Using a Proxy Server ==================== @@ -1904,6 +1849,4 @@ announcements on the `low-traffic packaging announcements list`_ and .. _low-traffic packaging announcements list: https://mail.python.org/mailman3/lists/pypi-announce.python.org/ .. _our survey on upgrades that create conflicts: https://docs.google.com/forms/d/e/1FAIpQLSeBkbhuIlSofXqCyhi3kGkLmtrpPOEBwr6iJA6SzHdxWKfqdA/viewform .. _the official Python blog: https://blog.python.org/ -.. _requests: https://requests.readthedocs.io/en/latest/user/authentication/#netrc-authentication -.. _Python standard library: https://docs.python.org/3/library/netrc.html .. _Python Windows launcher: https://docs.python.org/3/using/windows.html#launcher