Auth docs

docs/authentication.md

@@ -0,0 +1,63 @@
+# Authenticate pixi with a server
+
+You can authenticate pixi with a server like prefix.dev, a private quetz instance or anaconda.org.
+Different servers use different authentication methods. In this documentation page we detail how you can authenticate against the different servers and where the authentication information is stored.
+
+```
+Usage: pixi auth login [OPTIONS] <HOST>
+
+Arguments:
+  <HOST>  The host to authenticate with (e.g. repo.prefix.dev)
+
+Options:
+      --token <TOKEN>              The token to use (for authentication with prefix.dev)
+      --username <USERNAME>        The username to use (for basic HTTP authentication)
+      --password <PASSWORD>        The password to use (for basic HTTP authentication)
+      --conda-token <CONDA_TOKEN>  The token to use on anaconda.org / quetz authentication
+  -v, --verbose...                 More output per occurrence
+  -q, --quiet...                   Less output per occurrence
+  -h, --help                       Print help
+```
+
+The different options are "token", "conda-token" and "username + password".
+
+The token variant implements a standard "Bearer Token" authentication as is used on the prefix.dev platform.
+A Bearer Token is sent with every request as an additional header of the form `Authentication: Bearer <TOKEN>`.
+
+The conda-token option is used on anaconda.org and can be used with a quetz server. With this option, the token is sent as part of the URL following this scheme: `conda.anaconda.org/t/<TOKEN>/conda-forge/linux-64/...`.
+
+The last option, username & password, are used for "Basic HTTP Authentication". This is the equivalent of adding `http://user:password@myserver.com/...`. This authentication method can be configured quite easily with a reverse NGinx or Apache server and is thus commonly used in self-hosted systems.
+
+## Examples
+
+Login to prefix.dev:
+
+```sh
+pixi auth login prefix.dev --token pfx_jj8WDzvnuTEHGdAhwRZMC1Ag8gSto8
+```
+
+Login to anaconda.org:
+
+```sh
+pixi auth login anaconda.org --conda-token xy-72b914cc-c105-4ec7-a969-ab21d23480ed
+```
+
+Login to a basic HTTP secured server:
+
+```sh
+pixi auth login myserver.com --username user --password password
+```
+
+## Where does pixi store the authentication information?
+
+The storage location for the authentication information is system-dependent. By default, pixi tries to use the keychain to store this sensitive information securely on your computer.
+
+On Windows, the credentials are stored in the "credentials manager". Searching for `rattler` (the underlying library pixi uses) you should find any credentials stored by pixi (or other rattler-based programs).
+
+On macOS, the passwords are stored in the keychain. To access the password, you can use the `Keychain Access` program that comes pre-installed on macOS. Searching for `rattler` (the underlying library pixi uses) you should find any credentials stored by pixi (or other rattler-based programs).
+
+On Linux, one can use `GNOME Keyring` (or just Keyring) to access credentials that are securely stored by `libsecret`. Searching for `rattler` should list all the credentials stored by pixi and other rattler-based programs.
+
+## Fallback storage
+
+If you run on a server with none of the aformentioned keychains available, then pixi falls back to store the credentials in an _insecure_ JSON file. This JSON file is located at `~/.rattler/rattler_auth_store.json` and contains the credentials.

docs/cli.md

@@ -11,6 +11,7 @@ With `pixi` you can install packages in global space or local to the environment
 | `run`     | Runs the given command in a project's environment           |
 | `shell`   | Starts a shell in the project's environment                 |
 | `tasks`   | Manage tasks in your `pixi.toml` file                       |
+| `auth`    | Authenticate pixi with a server to access private channels  |
 
 ### Initialize a new project
 This command is used to create a new project.

src/cli/auth.rs

@@ -56,15 +56,14 @@ fn get_url(url: &str) -> anyhow::Result<String> {
         url.to_string()
     };
 
-    let host = if host == "prefix.dev" {
-        "repo.prefix.dev"
-    } else if host == "anaconda.org" {
-        "conda.anaconda.org"
+    let host = if host.matches('.').count() == 1 {
+        // use wildcard for top-level domains
+        format!("*.{}", host)
     } else {
-        &host
+        host
     };
 
-    Ok(host.to_string())
+    Ok(host)
 }
 
 fn login(args: LoginArgs, storage: AuthenticationStorage) -> anyhow::Result<()> {