When you create an API token, provide instructions for storing it in a more secure way than "plain text file on disk"

[alexwlchan]

What's the problem this feature will solve? When you create an API token, you get the following instructions:

Using this token

To use this API token:

• Set your username to __token__
• Set your password to the token value, including the pypi- prefix

For example, if you are using Twine to upload your projects to PyPI, set up your $HOME/.pypirc file like this:

[pypi]
  username = __token__
  password = pypi-AgEIc…

For further instructions on how to use this token, visit the PyPI help page.

Saving credentials to a plaintext file isn't particularly secure, and Twine has supports saving it in your keychain with keyring for years.

I think it would be good to have a brief mention of the keyring support here. It's a few more steps and shouldn't be the only option listed, but not mentioning it at all makes it easy for people to not realise that a more secure approach exists.

Describe the solution you'd like Add an additional paragraph like:

If you are using Twine and have keyring installed, you can save your API token securely in your system keychain:

keyring set https://upload.pypi.org/legacy/ __token__

Additional context

[alexwlchan]

This is useful for people who don't know you can store tokens using keyring, but also for people who know it's a thing but have forgotten how. That was me this evening!

I created an API token on a new computer, and I know I can save tokens in my keyring because I've done it before, but I couldn't remember the exact command. I spent several minutes trying to find out how to find the instructions in PyPI, because surely it would be mentioned somewhere there, and eventually realised it wasn't and went to find the Twine documentation instead.

[woodruffw]

Thanks for the request @alexwlchan! FWIW I think the reason we don't directly recommend keyring is twofold:

1. keyring is a fixed dep of twine, but there are platforms/deployments where it isn't installed (and twine handles this gracefully). These platforms are arguably niche, but are considered supported and it might be confusing to those users to have non-actionable keyring recommendations.
2. keyring is a bit of a black box from PyPI's vantage point: the defaults are good, but the system keyring isn't always available (for example, on Linux keyring will try the Secret Service D-Bus APIs, but there might not be a compatible keyring service on the host). Similarly, users might configure one of the older keyring.alt backends, some of which are intentionally insecure (e.g. PlaintextKeyring). The first case causes obscure errors that aren't easy for users to detect; the second might make users think that they're doing the secure thing when really they're effectively doing the same thing as .pypirc 🙂

TL;DR: I think it might make sense to update the language here to link to the Twine documentation (esp. since it's already linked to in other places), but I also think that directly encouraging keyring might be too confusing/hard to debug for a lot of people.

(Separately, we're generally encouraging people to use Trusted Publishing for authentication instead of manual API tokens, when they can. That might not apply in your case, however!)