# Getting started ```{toctree} :maxdepth: 1 :hidden: oauth2-recipe-tutorial ``` The `conda-auth` plugin improves the authentication experience for conda. Read below to learn how to start using it. ## Installation The plugin is available on conda-forge and can be installed like any other conda package: ``` conda install -c conda-forge conda-auth ``` ## Usage Once installed the plugin makes two new commands available: `conda auth login` and `conda auth logout`. The plugin supports various types of authentication schemes. Read below to learn how to use each. ### HTTP basic authentication To log in to a channel using HTTP basic authentication, run the following command: ``` conda auth login --basic ``` Once this has been run, you will be prompted for your username and password. For non-interactive automation, you can also specify username and password as command options: ``` conda auth login --basic --username "$USERNAME" --password "$PASSWORD" ``` ```{caution} Passing passwords directly on the command line may expose them in shell history or process listings. Prefer the prompt-based command when working interactively. ``` ### Token authentication The following examples are for authenticating with channels using token based authentication. For [anaconda.org](https://anaconda.org) channels: ``` conda auth login --token ``` You will then be prompted for your token. Optionally, you can specify the token value as an option for non-interactive automation: ``` conda auth login --token ``` ```{caution} Passing tokens directly on the command line may expose them in shell history or process listings. Prefer the prompt-based command when working interactively. ``` The request handler sends this as `Authorization: Bearer ` and does not overwrite an existing `Authorization` header. For services that expect a different token header, customize the header name and value template: ``` conda auth login --token \ --header X-Auth \ --token-template 'Token {token}' ``` The token template must include `{token}`. The `--token-header` and `--header-template` aliases are also accepted. ### OAuth 2.0/OIDC authentication OAuth 2.0 is available for OIDC services that support discovery plus authorization-code or device-code login flows. When a channel operator distributes its OAuth 2.0 configuration as a conda package (see [Creating an OAuth 2.0 auth recipe](oauth2-recipe-tutorial.md)), no additional flags are needed. Install the package and log in: ``` conda install resource-handler-auth conda auth login https://repo.example.com ``` #### Manual configuration If your channel operator does not provide a configuration package, you can supply the OAuth2 parameters directly on the command line: ``` conda auth login https://repo.example.com --oauth2 \ --oauth-issuer-url https://idp.example.com \ --oauth-client-id my-client \ --oauth-flow auto ``` The `--oauth2`, `--basic`, and `--token` flags are optional when the auth type is already configured in `channel_settings` in your condarc. If a matching entry exists, the login command infers the auth type automatically. Explicit OAuth 2.0 command-line options override their corresponding `channel_settings` values. Omitted values come from `channel_settings` and then built-in defaults. Client secrets are accepted only through the command line or interactive prompt and are stored in the system keyring. Supported OAuth 2.0 modes: - `auto`: tries browser authorization-code login first, and falls back to device-code when the browser cannot be opened - `auth-code`: browser login with a localhost callback and PKCE - `device-code`: headless login for SSH and terminal-only environments Additional OAuth options include `--oauth-client-secret`, repeatable `--oauth-scope`, `--oauth-redirect-uri`, and `--user-agent`. conda-auth refreshes OAuth 2.0 access tokens before expiry when a refresh token is available, and attempts token revocation on logout when the OAuth server advertises a revocation endpoint. When supplied, the OAuth client secret is stored only in the credential record in the system keyring. It is not written to `channel_settings` in the condarc. The password grant, implicit flow, and client credentials grant are not supported. ### Channel transports Conda auth supports authenticated HTTP(S) channel services. Remote channels must use HTTPS by default, and FTP and file channels are not supported by these auth handlers. Conda's `s3://` support currently uses boto3's normal AWS credential chain, such as environment variables, profiles, and instance credentials. Conda auth does not set process-wide AWS environment variables. First-class channel-scoped S3 credentials need a future conda-side S3 credential hook. For an explicitly trusted plaintext HTTP channel, opt in per channel: ``` conda auth login http://example.com/my-protected-channel --basic --allow-plaintext-http ``` ```{caution} Plaintext HTTP sends credentials without transport encryption. Prefer HTTPS whenever possible, and only use `--allow-plaintext-http` for endpoints you explicitly trust. ``` ### Logging out of a channel If you want to clear your user credentials from your computer for any reason, you can do so by running the `conda auth logout` command. All you have to do is provide a channel name, and it will find and remove your credentials from the password store and user conda configuration. You can do this by running the following command: ``` conda auth logout ``` Both `login` and `logout` support JSON output for automation: ``` conda auth login --token --json conda auth logout --json ``` `status` output is redacted and does not print stored tokens, passwords, OAuth 2.0 access tokens, or refresh tokens. ### Storage backend unavailable? Conda auth relies on the [keyring](https://github.com/jaraco/keyring) package to store its passwords and secrets. Because of this, it only supports a limited number of operating systems, mostly desktop operating systems like Windows, OSX and several Linux variants. If you want to use conda-auth, but are not using a supported operating system, you can install the [keyring-alt](https://github.com/jaraco/keyrings.alt) package: ``` conda install -c conda-forge keyrings.alt ``` ```{caution} This method stores passwords and secrets in a plain text file on the filesystem and may not be acceptable for production usage. Please read the [project's README](https://github.com/jaraco/keyrings.alt) for more information. ``` ## Reporting bugs Have you found a bug you want to let us know about? Please create an issue at our [GitHub project](https://github.com/conda-incubator/conda-auth/issues/new/choose). And thank you for helping us improve conda auth!