From 47b6fe6e0da1c3d6f0e827cdaa81f52ecec7aedb Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 26 Jan 2024 15:38:21 -0600 Subject: [PATCH 1/5] docs(config): Help credentials users find out more about cargo:token --- src/doc/src/reference/config.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index 25e17ac907f6..6215aa0fad70 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -299,7 +299,7 @@ Cargo will search `PATH` for its executable. Configuration values with sensitive information are stored in the `$CARGO_HOME/credentials.toml` file. This file is automatically created and updated -by [`cargo login`] and [`cargo logout`] when using the `cargo:token` credential provider. +by [`cargo login`] and [`cargo logout`] when using the [`cargo:token`] credential provider. It follows the same format as Cargo config files. @@ -1320,6 +1320,7 @@ Sets the width for progress bar. [source replacement]: source-replacement.md [revision]: https://git-scm.com/docs/gitrevisions [registries]: registries.md +[`cargo:token`]: registry-authentication.md#cargotoken [crates.io]: https://crates.io/ [target triple]: ../appendix/glossary.md#target '"target" (glossary)' [``]: ../appendix/glossary.md#target '"target" (glossary)' From 299f03161928741107bf6971f9c1c533889d588c Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 26 Jan 2024 15:39:16 -0600 Subject: [PATCH 2/5] docs(config): Group high-level with schema-based credentials descriptions --- src/doc/src/reference/config.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index 6215aa0fad70..4cbc4b7b9f10 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -301,6 +301,10 @@ Configuration values with sensitive information are stored in the `$CARGO_HOME/credentials.toml` file. This file is automatically created and updated by [`cargo login`] and [`cargo logout`] when using the [`cargo:token`] credential provider. +Tokens are used by some Cargo commands such as [`cargo publish`] for +authenticating with remote registries. Care should be taken to protect the +tokens and to keep them secret. + It follows the same format as Cargo config files. ```toml @@ -311,10 +315,6 @@ token = "…" # Access token for crates.io token = "…" # Access token for the named registry ``` -Tokens are used by some Cargo commands such as [`cargo publish`] for -authenticating with remote registries. Care should be taken to protect the -tokens and to keep them secret. - As with most other config values, tokens may be specified with environment variables. The token for [crates.io] may be specified with the `CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may From 88694ae7840f6e03cf21b82ccee73ad60fd65514 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 26 Jan 2024 15:41:48 -0600 Subject: [PATCH 3/5] docs(auth): With recommended config, call out precedence I thought the recommendation was doing the opposite of what I expected until I dug further. While this is covered in the config docs, we should explicitly call it out. --- src/doc/src/reference/registry-authentication.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/doc/src/reference/registry-authentication.md b/src/doc/src/reference/registry-authentication.md index 0508900c00c1..d4bf09d5c30b 100644 --- a/src/doc/src/reference/registry-authentication.md +++ b/src/doc/src/reference/registry-authentication.md @@ -45,6 +45,7 @@ global-credential-providers = ["cargo:token", "cargo:libsecret"] global-credential-providers = ["cargo:token", "cargo:wincred"] ``` +Note that later entries have higher precedence. See [`registry.global-credential-providers`](config.md#registryglobal-credential-providers) for more details. From 0a7fbf528500bb6e2ada524ff80ac6a6c842f75a Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 26 Jan 2024 15:43:36 -0600 Subject: [PATCH 4/5] docs(auth): Merge recommended configurations Before, it made it look like you needed to maintain a platform-specific `.cargo/config.toml` but it can instead be cross-platform. --- .../src/reference/registry-authentication.md | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/src/doc/src/reference/registry-authentication.md b/src/doc/src/reference/registry-authentication.md index d4bf09d5c30b..ab66f5b0d633 100644 --- a/src/doc/src/reference/registry-authentication.md +++ b/src/doc/src/reference/registry-authentication.md @@ -24,25 +24,10 @@ to look in Cargo's [credentials](config.md#credentials) file or environment vari Some private registries may also recommend a registry-specific credential-provider. Check your registry's documentation to see if this is the case. -### macOS configuration ```toml # ~/.cargo/config.toml [registry] -global-credential-providers = ["cargo:token", "cargo:macos-keychain"] -``` - -### Linux (libsecret) configuration -```toml -# ~/.cargo/config.toml -[registry] -global-credential-providers = ["cargo:token", "cargo:libsecret"] -``` - -### Windows configuration -```toml -# %USERPROFILE%\.cargo\config.toml -[registry] -global-credential-providers = ["cargo:token", "cargo:wincred"] +global-credential-providers = ["cargo:token", "cargo:libsecret", "cargo:macos-keychain", "cargo:wincred"] ``` Note that later entries have higher precedence. From 5ceb1b2d6627978b8a50871f58941f961e17b8e0 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 26 Jan 2024 15:45:33 -0600 Subject: [PATCH 5/5] docs(auth): Don't get in the way of recommendation and commentary --- src/doc/src/reference/registry-authentication.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/src/doc/src/reference/registry-authentication.md b/src/doc/src/reference/registry-authentication.md index ab66f5b0d633..6a6c5ce28921 100644 --- a/src/doc/src/reference/registry-authentication.md +++ b/src/doc/src/reference/registry-authentication.md @@ -19,20 +19,18 @@ which defaults to: * Unix: `~/.cargo/config.toml` This recommended configuration uses the operating system provider, with a fallback to `cargo:token` -to look in Cargo's [credentials](config.md#credentials) file or environment variables. - -Some private registries may also recommend a registry-specific credential-provider. Check your -registry's documentation to see if this is the case. - +to look in Cargo's [credentials](config.md#credentials) file or environment variables: ```toml # ~/.cargo/config.toml [registry] global-credential-providers = ["cargo:token", "cargo:libsecret", "cargo:macos-keychain", "cargo:wincred"] ``` - -Note that later entries have higher precedence. +*Note that later entries have higher precedence. See [`registry.global-credential-providers`](config.md#registryglobal-credential-providers) -for more details. +for more details.* + +Some private registries may also recommend a registry-specific credential-provider. Check your +registry's documentation to see if this is the case. ## Built-in providers Cargo includes several built-in credential providers. The available built-in providers