Improve documentation about private registry credentials

[ranger-ross]

Problem

In the Cargo Book it states that you can set a token like so.

[registries.<name>]
token = "…"   # Access token for the named registry

However, the Cargo uses this token directly in the Authorization header without modifying it.
Many private registries will expect the token in the bearer format (Bearer {token}) so you will need to add Bearer to the token field in credentials.toml.

[registries.<name>]
token = "Bearer my-token-123"

Generally when I see a token field in a config file, I expect to just add my token without caring about the format the registry expected the token to be delivered in. This lead to a good amount of confusion today 😅

Possible Solution(s)

1. At the bare minimum we should at least improve the documentation in the Cargo book about how the token is used and that the user might need to add the format like Basic or Bearer to the token field.
2. An alternative would be to retry the request to the registry prefixing the token with Bearer if there is a 401 response.

Notes

There is already precedence for retry failed request for getting the index config.json so extending it to downloading crates seems reasonable.
See the sparse authentication docs

Version

cargo 1.83.0 (5ffbef321 2024-10-29)
release: 1.83.0
commit-hash: 5ffbef3211a8c378857905775a15c5b32a174d3b
commit-date: 2024-10-29
host: x86_64-unknown-linux-gnu
libgit2: 1.8.1 (sys:0.19.0 vendored)
libcurl: 8.9.0-DEV (sys:0.4.74+curl-8.9.0 vendored ssl:OpenSSL/1.1.1w)
ssl: OpenSSL 1.1.1w  11 Sep 202

[epage]

At the bare minimum we should at least improve the documentation in the Cargo book about how the token is used and that the user might need to add the format like Basic or Bearer to the token field.

What I would want to be cautious about is confusing people who don't need this, particularly but the fact that the most common registry people will use does not do this.

An alternative would be to retry the request to the registry prefixing the token with Bearer if there is a 401 response.

I don't know enough about authentication conventions and best practices to weigh on this.

Alternatively, should it be the responsibility of the registry that needs it to advertise the token with the Bearer prefix?

[ranger-ross]

Alternatively, should it be the responsibility of the registry that needs it to advertise the token with the Bearer prefix?

Well I do not disagree with this, but even if the registry does document that the token needs to be sent in Bearer scheme its difficult to know a user to know what authentication scheme Cargo will send it as. I think its not unreasonable to assume Cargo will send a token as Bearer (which it does not) as that is generally the most common scheme for sending tokens in requests.

Perhaps just adding something like this to the Cargo book would be enough to avoid confusion.

NOTE: Cargo will use the token as is in the `Authorization` header without modification. 
For registries that require an authentication scheme like (like Bearer) the `registry.<name>.token` should be prefixed with the scheme name (ie. `Bearer `) by the user.

[weihanglo]

NOTE: Cargo will use the token as is in the Authorization header without modification.
For registries that require an authentication scheme like (like Bearer) the registry.<name>.token should be prefixed with the scheme name (ie. Bearer ) by the user.

This looks fine, though I would generally recommend private registries moving away from plain token, and use credential provider instead.