Update the index.authenticate docs (#12102)

Follow-up to #11896 

Reframes the documentation a bit.

Looking into why the `[index]` child fields aren't generate in the
reference correctly too.

crates/uv-auth/src/policy.rs

@@ -1,18 +1,28 @@
 use rustc_hash::FxHashMap;
 use url::Url;
 
+/// When to use authentication.
 #[derive(
     Copy, Clone, Debug, Default, Hash, Eq, PartialEq, serde::Serialize, serde::Deserialize,
 )]
 #[serde(rename_all = "kebab-case")]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub enum AuthPolicy {
-    /// Try unauthenticated request. Fallback to authenticated request.
+    /// Authenticate when necessary.
+    ///
+    /// If credentials are provided, they will be used. Otherwise, an unauthenticated request will
+    /// be attempted first. If the request fails, uv will search for credentials. If credentials are
+    /// found, an authenticated request will be attempted.
     #[default]
     Auto,
     /// Always authenticate.
+    ///
+    /// If credentials are not provided, uv will eagerly search for credentials. If credentials
+    /// cannot be found, uv will error instead of attempting an unauthenticated request.
     Always,
     /// Never authenticate.
+    ///
+    /// If credentials are provided, uv will error. uv will not search for credentials.
     Never,
 }
 

crates/uv-distribution-types/src/index.rs

@@ -82,19 +82,7 @@ pub struct Index {
     /// publish-url = "https://upload.pypi.org/legacy/"
     /// ```
     pub publish_url: Option<Url>,
-    /// The authentication policy for the index.
-    ///
-    /// There are three policies: "auto", "always", and "never".
-    ///
-    /// * "auto" will first attempt an unauthenticated request to the index.
-    ///   If that fails it will attempt an authenticated request.
-    /// * "always" will always attempt to make an authenticated request and will
-    ///   fail if the authenticated request fails.
-    /// * "never" will never attempt to make an authenticated request and will
-    ///   fail if an authenticated request fails.
-    ///
-    /// The authentication policy will apply to requests made to URLs with
-    /// this index URL as a prefix.
+    /// When uv should use authentication for requests to the index.
     ///
     /// ```toml
     /// [[tool.uv.index]]

docs/configuration/authentication.md

@@ -50,14 +50,23 @@ argument to uv, or set `UV_KEYRING_PROVIDER=subprocess`.
 
 Authentication may be used for hosts specified in the following contexts:
 
+- `[index]`
 - `index-url`
 - `extra-index-url`
 - `find-links`
 - `package @ https://...`
 
+See the [index authentication documentation](./indexes.md#authentication) for details on
+authenticating index URLs.
+
 See the [`pip` compatibility guide](../pip/compatibility.md#registry-authentication) for details on
 differences from `pip`.
 
+## Authentication with alternative package indexes
+
+See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for
+details on authentication with popular alternative Python package indexes.
+
 ## Custom CA certificates
 
 By default, uv loads certificates from the bundled `webpki-roots` crate. The `webpki-roots` are a
@@ -93,14 +102,3 @@ insecure.
 
 Use `allow-insecure-host` with caution and only in trusted environments, as it can expose you to
 security risks due to the lack of certificate verification.
-
-## Authentication with alternative package indexes
-
-See the [alternative indexes integration guide](../guides/integration/alternative-indexes.md) for
-details on authentication with popular alternative Python package indexes.
-
-## Configuring authentication for indexes
-
-It is possible to configure how uv will handle authentication for requests to indexes. See
-[configuring authentication for indexes](indexes.md#configuring-authentication-for-indexes) for more
-details.

docs/configuration/indexes.md

@@ -135,13 +135,19 @@ Users can opt in to alternate index behaviors via the`--index-strategy` command-
 While `unsafe-best-match` is the closest to pip's behavior, it exposes users to the risk of
 "dependency confusion" attacks.
 
-## Providing credentials
+## Authentication
 
-Most private registries require authentication to access packages, typically via a username and
+Most private package indexes require authentication to access packages, typically via a username and
 password (or access token).
 
-To authenticate with a provide index, either provide credentials via environment variables or embed
-them in the URL.
+!!! tip
+
+    See the [alternative index guide](../guides/integration/alternative-indexes.md) for details on
+    authenticating with specific private index providers, e.g., from AWS, Azure, or GCP.
+
+### Providing credentials directly
+
+Credentials can be provided directly via environment variables or by embedding them in the URL.
 
 For example, given an index named `internal-proxy` that requires a username (`public`) and password
 (`koala`), define the index (without credentials) in your `pyproject.toml`:
@@ -175,27 +181,47 @@ url = "https://public:koala@pypi-proxy.corp.dev/simple"
 For security purposes, credentials are _never_ stored in the `uv.lock` file; as such, uv _must_ have
 access to the authenticated URL at installation time.
 
-## Configuring authentication for indexes
+### Using credential providers
 
-By default, when sending requests to an index, uv will first attempt an unauthenticated request. If
-that fails, it will search for credentials and attempt an authenticated request.
+In addition to providing credentials directly, uv supports discovery of credentials from netrc and
+keyring. See the [HTTP authentication](./authentication.md#http-authentication) documentation for
+details on setting up specific credential providers.
 
-It is possible to change this default behavior for an index by specifying when to authenticate:
+By default, uv will attempt an unauthenticated request before querying providers. If the request
+fails, uv will search for credentials. If credentials are found, an authenticated request will be
+attempted.
 
-```toml
+!!! note
+
+    If a username is set, uv will search for credentials before making an unauthenticated request.
+
+Some indexes (e.g., GitLab) will forward unauthenticated requests to a public index, like PyPI —
+which means that uv will not search for credentials. This behavior can be changed per-index, using
+the `authenticate` setting. For example, to always search for credentials:
+
+```toml hl_lines="4"
 [[tool.uv.index]]
 name = "example"
 url = "https://example.com/simple"
 authenticate = "always"
 ```
 
-The following values are supported for `authenticate`:
+When `authenticate` is set to `always`, uv will eagerly search for credentials and error if
+credentials cannot be found.
 
-- `auto` (default): First attempt an unauthenticated request. If that fails, search for credentials
-  and attempt an authenticated request.
-- `always`: Always search for credentials and attempt an authenticated request. If that fails, the
-  request fails.
-- `never`: Only attempt an unauthenticated request. If that fails, the request fails.
+### Disabling authentication
+
+To prevent leaking credentials, authentication can be disabled for an index:
+
+```toml hl_lines="4"
+[[tool.uv.index]]
+name = "example"
+url = "https://example.com/simple"
+authenticate = "never"
+```
+
+When `authenticate` is set to `never`, uv will never search for credentials for the given index and
+will error if credentials are provided directly.
 
 ## `--index-url` and `--extra-index-url`
 

uv.schema.json

@@ -558,23 +558,24 @@
       ]
     },
     "AuthPolicy": {
+      "description": "When to use authentication.",
       "oneOf": [
         {
-          "description": "Try unauthenticated request. Fallback to authenticated request.",
+          "description": "Authenticate when necessary.\n\nIf credentials are provided, they will be used. Otherwise, an unauthenticated request will be attempted first. If the request fails, uv will search for credentials. If credentials are found, an authenticated request will be attempted.",
           "type": "string",
           "enum": [
             "auto"
           ]
         },
         {
-          "description": "Always authenticate.",
+          "description": "Always authenticate.\n\nIf credentials are not provided, uv will eagerly search for credentials. If credentials cannot be found, uv will error instead of attempting an unauthenticated request.",
           "type": "string",
           "enum": [
             "always"
           ]
         },
         {
-          "description": "Never authenticate.",
+          "description": "Never authenticate.\n\nIf credentials are provided, uv will error. uv will not search for credentials.",
           "type": "string",
           "enum": [
             "never"
@@ -735,7 +736,7 @@
       ],
       "properties": {
         "authenticate": {
-          "description": "The authentication policy for the index.\n\nThere are three policies: \"auto\", \"always\", and \"never\".\n\n* \"auto\" will first attempt an unauthenticated request to the index. If that fails it will attempt an authenticated request. * \"always\" will always attempt to make an authenticated request and will fail if the authenticated request fails. * \"never\" will never attempt to make an authenticated request and will fail if an authenticated request fails.\n\nThe authentication policy will apply to requests made to URLs with this index URL as a prefix.\n\n```toml [[tool.uv.index]] name = \"my-index\" url = \"https://<omitted>/simple\" authenticate = \"always\" ```",
+          "description": "When uv should use authentication for requests to the index.\n\n```toml [[tool.uv.index]] name = \"my-index\" url = \"https://<omitted>/simple\" authenticate = \"always\" ```",
           "default": "auto",
           "allOf": [
             {