mirror of https://github.com/pypa/pip
Merge pull request #10027 from pradyunsg/topic/authentication
Add a topic guide for Authentication
This commit is contained in:
commit
8fe001193d
|
@ -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.
|
|
@ -9,4 +9,6 @@ This section of the documentation is currently being fleshed out. See
|
|||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
authentication
|
||||
```
|
||||
|
|
|
@ -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 <https://en.wikipedia.org/wiki/Percent-encoding#Percent-encoding_reserved_characters>`_
|
||||
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 <https://github.com/pypa/pip/issues/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 <https://docs.python.org/3/library/netrc.html>`_,
|
||||
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
|
||||
|
|
Loading…
Reference in New Issue