diff --git a/_articles/miscellaneous/cli-auth-challenges.md b/_articles/miscellaneous/cli-auth-challenges.md index b21845e1..147ea21d 100644 --- a/_articles/miscellaneous/cli-auth-challenges.md +++ b/_articles/miscellaneous/cli-auth-challenges.md @@ -9,6 +9,11 @@ tags: [cli, captcha] The August 2021 release of Bitwarden (**2021-09-21**) introduced [Captcha](https://www.hcaptcha.com/about){:target="\_blank"} requirements to increase security against bot traffic. On the CLI, Captcha challenges are substituted with authentication challenges that can validated using your account's [Personal API Key]({{site.baseurl}}/article/personal-api-key) `client_secret`. + +{% callout success %} +**For automated workflows or for providing access to an external application**, we recommend using the `bw login --apikey` [method]({{site.baseurl}}/article/cli/#using-an-api-key). This method follows a more predictable authentication flow and revoking an application or machine's access can be achieved by rotating the [API Key]({{site.baseurl}}/article/personal-api-key/#rotate-your-api-key). +{% endcallout %} + ## Get your Personal API Key To get your Personal API Key: @@ -22,13 +27,9 @@ To get your Personal API Key: Depending on your preferences, you can [save an environment variable](#answer-challenges-with-an-environment-variable) to automatically pass authentication challenges or [manually enter](#using-the-prompt) your `client_secret` whenever a challenge is made: -{% callout success %} -Aside from using environment variable, any possible challenge is automatically bypassed when using the `bw login --apikey` method. [Learn more]({{site.baseurl}}/article/cli/#using-an-api-key). -{% endcallout %} - ### Answer Challenges with an Environment Variable -Authentication challenges will look for a non-empty environment variables `BW_CLIENTSECRET` before prompting you to enter one manually. Saving this variable with the [retrieved client_secret value](#get-your-personal-api-key) will allow you to automatically pass authentication challenges. To save this environment variable: +Authentication challenges will look for a non-empty environment variable `BW_CLIENTSECRET` before prompting you to enter one manually. Saving this variable with the [retrieved client_secret value](#get-your-personal-api-key) will allow you to automatically pass authentication challenges. To save this environment variable: {% icon fa-linux %} {% icon fa-apple %} Bash ``` diff --git a/_articles/miscellaneous/cli.md b/_articles/miscellaneous/cli.md index c247060b..e18c4a33 100644 --- a/_articles/miscellaneous/cli.md +++ b/_articles/miscellaneous/cli.md @@ -130,98 +130,101 @@ sudo snap install bw ## Log In -Logging in to the Bitwarden CLI authenticates you with the [configured](#config) Bitwarden server and syncs your Vault. To log in to Bitwarden, use the `login` command with one of the following login workflow options: +There are three methods for logging in to the Bitwarden CLI using the `login` command, each of which is suited to different situations. Please review the following options to determine which method to use: - - [Using email and password](#using-email-and-password) - - [Using an API key](#using-an-api-key) - - [Using SSO](#using-sso) +- [Using Email and Password](#using-email-and-password) +- [Using an API Key](#using-an-api-key) +- [Using SSO](#using-sso) -### Using email and password +{% callout success %} +Logging in [Using Email and Password](#using-email-and-password) uses your Master Password and can therefore string together the `login` and `unlock` commands to authenticate your identity and decrypt your Vault in tandem. [Using an API Key](#using-an-api-key) or [SSO](#using-sso) will require you to follow-up the `login` command with an explicit `bw unlock` if you will be working with Vault data directly. -Logging in with email and password authenticates you with Bitwarden servers, syncs your Vault, **and unlocks your Vault**. This is the only method that automatically unlocks your Vault. To log in with email and password use: +This is because your Master Password is the source of the key needed to decrypt Vault data. There are, however, a few commands that do not require your Vault to be decrypted, including `config`, `encode`, and `generate`, `update`, and `status`. +{% endcallout %} + +### Using Email and Password + +Logging in with email and password is **recommended for interactive sessions**. To log in with email and password: ``` bw login ``` -This command will initiate a prompt for your **Email address**, **Master password**, and (if [enabled]({{site.baseurl}}/article/setup-two-step-login/)) a **Two-step login code**. +This will initiate a prompt for your **Email address**, **Master password**, and ([if enabled]({{site.baseurl}}/article/setup-two-step-login/)) a **Two-step login code**. The CLI currently supports Two-step login via [authenticator]({{site.baseurl}}/article/setup-two-step-login-authenticator/), [email]({{site.baseurl}}/article/setup-two-step-login-email/), or [Yubikey]({{site.baseurl}}/article/setup-two-step-login-yubikey/). -{% callout info %} -You *can* string this together into a single command as in the following example, however this is not recommended for security reasons. +You *can* string these factors together into a single command as in the following example, however this is not recommended for security reasons. ``` bw login [email] [password] --method --code ``` -See [Appendices → Enums](#enums) for `` values. -{% endcallout %} - -### Using an API key +See [Appendices → Enums](#enums) for Two-step Login `` values. {% callout success %} **Getting prompted for additional authentication** or getting a `Your authentication request appears to be coming from a bot.` error? Use your API Key `client_secret` to answer the authentication challenge. [Learn more]({{site.baseurl}}/article/cli-auth-challenges/). {% endcallout %} -Logging in with a [Personal API Key]({{site.baseurl}}/article/personal-api-key/) authenticates you with Bitwarden servers, syncs your Vault, but **does not unlock your Vault**. After logging in with an API key, you will be required to unlock your Vault using your Master Password. To log in with an API key use: +### Using an API Key + +Logging in with the [Personal API Key]({{site.baseurl}}/article/personal-api-key/) is **recommended for automated workflows or providing access to an external application**. To log in with the API Key: ``` bw login --apikey ``` -This command will initiate a prompt for your personal `client_id` and `client_secret`. -{% callout success %} -When logging in with an API key, the CLI will first look for non-empty environment variables `BW_CLIENTID` and `BW_CLIENTSECRET` before initiating a prompt for `client_id` and `client_secret`. +This will initiate a prompt for your personal `client_id` and `client_secret`. Once your session is authenticated using these values, you can use the `unlock` command ([learn more](#unlock)). -If you don't want to be prompted for the `client_id` and `client_secret` every time, you can save these values to `BW_CLIENTID` and `BW_CLIENTSECRET` respectively. -{% endcallout %} +#### Using API Key Environment Variables + +In scenarios where automated work is being done with the Bitwarden CLI, you can save environment variables to prevent the need for manual intervention at authentication. + +|Environment Variable Name|Required Value| +|-------------------------|--------------| +|BW_CLIENTID|`client_id`| +|BW_CLIENTSECRET|`client_secret`| ### Using SSO -Logging in with [SSO]({{site.baseurl}}/article/about-sso/) authenticates you with Bitwarden servers, syncs your Vault, but **does not unlock your Vault**. After logging in with SSO, you will be required to unlock your Vault using your Master Password. To log in with SSO use: +Logging in with the [SSO]({{site.baseurl}}/article/about-sso/) is **recommended if an Organization requires SSO Authentication**. To log in with SSO: ``` bw login --sso ``` -This command will initiate the SSO authentication flow in your web browser. +This will initiate the [SSO authentication flow]({{site.baseurl}}/article/using-sso/#login-using-sso) in your web browser. Once your session is authenticated, you can use the `unlock` command ([learn more](#unlock)). -### Two-step login +## Unlock -The CLI currently supports [two-step login]({{site.baseurl}}/article/setup-two-step-login/) via [authenticator]({{site.baseurl}}/article/setup-two-step-login-authenticator/), [email]({{site.baseurl}}/article/setup-two-step-login-email/), or [Yubikey]({{site.baseurl}}/article/setup-two-step-login-yubikey/). If you have one of these methods enabled, you will be required to enter your two-step login code to log in. If you have multiple methods enabled, you will be prompted first to select which method to use. +[Using an API Key](#using-an-api-key) or [SSO](#using-sso) to log in will require you to follow-up the `login` command with an explicit `bw unlock` if you will be working with Vault data directly. -{% callout info %} -You *can* pass your two-step login method and code as options, as in the following example. - -``` -bw login [email] [password] --method --code -``` - -See [Appendices → Enums](#enums) for `` values. -{% endcallout %} - -## Session Management - -Logging in [using email and password](#using-email-and-password) is the only method which automatically **unlocks** your Vault. All other options will subsequently prompt you to unlock your Vault using your Master Password. - -In the CLI, unlocking your Vault generates a **session key** which acts as the decryption key used to interact with data in your Vault. The [session key must be used](#using-a-session-key) to perform any command that touches Vault data (e.g. `list`, `get`, `edit`). You can generate a new session key at any time using: +Unlocking your Vault generates a **session key** which acts as a session-specific decryption key used to interact with data in your Vault. The [session key must be used](#using-a-session-key) to perform any command that touches Vault data (e.g. `list`, `get`, `edit`). Generate a new session key at any time using: ``` bw unlock ``` -This command will prompt your for your Master Password and generate a new session key. +### Unlock Options -You can also **lock** (i.e. destroy any active session key) using: +You can use the `--passwordenv ` or `--passwordfile ` options with `bw unlock` to retrieve your Master Password rather than enter it manually as in the following examples: +1. ``` +bw unlock --passwordenv BW_PASSWORD ``` -bw lock + + will look for an environment variable `BW_PASSWORD`. If `BW_PASSWORD` is non-empty and has correct values, the CLI will successfully and unlock and return a session key. +2. ``` +bw unlock --passwordfile ~/Users/Me/Documents/mp.txt ``` + will look for the file `~Users/Me/Documents/mp.txt` (which must have your Master Password as the first line). If the file is non-empty and has a correct value, the CLI will successfully unlock and return a session key. + + {% callout warning %}If you use the `--passwordfile` option, protect your password file by locking access down to only the user who needs run `bw unlock` and only providing read access to that user.{% endcallout %} + ### Using a Session Key -The typical way to use a session key is to set a `BW_SESSION` environment variable with the session key's value. When you log in and unlock your Vault using any one of the [above methods](#log-in), the CLI will return both a `export BW_SESSION` (Bash) and `env:BW_SESSION` (PowerShell) command, including your session key, that can be easily copied and pasted to save the required environment variable. +When you unlock your Vault using `bw login` with [email and password](#using-email-and-password) or `bw unlock`, the CLI will return both a `export BW_SESSION` (Bash) and `env:BW_SESSION` (PowerShell) command, including your session key. Copy and paste the relevant entry to save the required environment variable. -When you set the `BW_SESSION` environment variable, `bw` commands will reference that variable and can be run cleanly, for example: +With the `BW_SESSION` environment variable set, `bw` commands will reference that variable and can be run cleanly, for example: ``` export BW_SESSION="5PBYGU+5yt3RHcCjoeJKx/wByU34vokGRZjXpSH7Ylo8w==" @@ -229,16 +232,18 @@ export BW_SESSION="5PBYGU+5yt3RHcCjoeJKx/wByU34vokGRZjXpSH7Ylo8w==" bw list items ``` -The `BW_SESSION` environment variable is only tied to the active terminal session, so closing your terminal window is equivalent to locking your Vault. - Alternatively, if you don't set the environment variable, you can pass the session key as an option with each `bw` command: ``` bw list items --session "5PBYGU+5yt3RHcCjoeJKx/wByU34vokGRZjXpSH7Ylo8w==" ``` -{% callout info %} -It is *possible* to persist your session key to your environment (for example, exporting it in `.bashrc`), however, **we do not recommend doing so**. Considering their use, session keys are not well-suited to persisting on an unprotected disk. +{% callout success %} +The `BW_SESSION` environment variable is only tied to the active terminal session, so closing your terminal window is equivalent to locking your Vault. You can also destroy an active session key to lock your Vault by running: + +``` +bw lock +``` {% endcallout %} ## Core Commands diff --git a/_articles/miscellaneous/personal-api-key.md b/_articles/miscellaneous/personal-api-key.md index 1751f29a..271f9d56 100644 --- a/_articles/miscellaneous/personal-api-key.md +++ b/_articles/miscellaneous/personal-api-key.md @@ -7,7 +7,7 @@ popular: false tags: [api key, cli] --- -Your Bitwarden Personal API Key can be used as an alternative method for authenticating into the Command Line Interface (CLI). +Your Bitwarden Personal API Key can be used as a method for authenticating into the Command Line Interface (CLI). {% callout info %} Your Personal API Key is **not the same** as the [Organization API Key]({{site.baseurl}}/article/public-api/#authentication) used to access the [Bitwarden Public API]({{site.baseurl}}/article/public-api/) or [Directory Connector]({{site.baseurl}}/article/directory-sync/). Personal API Keys will have a `client_id` with format `"user.clientId"`, while Organization API Keys will have a `client_id` with format `"organization.ClientId"`. @@ -35,14 +35,19 @@ Rotating your key will invalidate your previous key and all active sessions usin ## Authenticate using your API Key -To use your API Key to authenticate into the CLI, enter the following command: +Logging in to the CLI with the Personal API Key is **recommended for automated workflows or providing access to an external application**. To log in with the API Key: + ``` bw login --apikey ``` -which will prompt you to enter the obtained `client_id` and `client_secret` to authenticate. Once you enter these values, enter your Master Password to decrypt your Vault. For more information, see [Bitwarden command line tool (CLI)]({{site.baseurl}}/article/cli/). -### Environment Variables +This will initiate a prompt for your personal `client_id` and `client_secret`. Once your session is authenticated using these values, you'll be prompted to use the `unlock` command ([learn more]({{site.baseurl}}/article/cli/#unlock)). -The Bitwarden CLI will look for non-empty environment variables `BW_CLIENTID` or `BW_CLIENTSECRET`. Save these environment variables with your `client_id` and `client_secret` to prevent Bitwarden from prompting you every time. +#### Using API Key Environment Variables -You will still need to enter your Master Password to decrypt your Vault. +In scenarios where automated work is being done with the Bitwarden CLI, you can save environment variables to prevent the need for manual intervention at authentication. + +|Environment Variable Name|Required Value| +|-------------------------|--------------| +|BW_CLIENTID|`client_id`| +|BW_CLIENTSECRET|`client_secret`| diff --git a/_articles/organizations/public-api.md b/_articles/organizations/public-api.md index a200371b..a89e5a1f 100644 --- a/_articles/organizations/public-api.md +++ b/_articles/organizations/public-api.md @@ -11,7 +11,7 @@ order: "16" The Bitwarden Public API provides Organizations a suite of tools for managing members, collections, groups, event logs, and policies. {% callout success %} -For automating **management of Vault items**, we recommend using the [CLI]({{site.baseurl}}/article/cli/). Access to Vault items relies on Vault decryption, which must be done with a Username and Master Password rather than an [API Key](#authentication). +For **management of Vault items**, use the [CLI]({{site.baseurl}}/article/cli/). Access to Vault items relies on Vault decryption, which must be done with a Master Password. {% endcallout %} The Public API is a RESTful API with predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. @@ -42,6 +42,10 @@ For Self-hosted, `https://your.domain.com/identity/connect/token`. The API uses bearer access tokens to authenticate with protected API endpoints. Bitwarden uses an [OAuth2 Client Credentials](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/){:target="_blank"} application request flow to grant bearer access tokens from the endpoint. Authentication requests take `client_id` and `client_secret` as required parameters. +{% callout success %} +The API Key used to authenticate with the Public API is **not the same** as the [Personal API Key]({{site.baseurl}}/article/personal-api-key). Organization API Keys will have a `client_id` with format `"organization.ClientId"`, whereas Personal API Keys will have a `client_id` with format `"user.clientId"`. +{% endcallout %} + The API Key `client_id` and `client_secret` can be obtained by an **Owner** from the Web Vault by navigating to Organization **Settings** → **My Organization** and scrolling down to the **API Key** section: {% image organizations/org-api-key.png Get Organization API Key %} @@ -49,7 +53,7 @@ The API Key `client_id` and `client_secret` can be obtained by an **Owner** from If, as an owner, you want to share the API Key with an Admin or other user, use a secure communication method like [Bitwarden Send]({{site.baseurl}}/article/about-send/). {% callout warning %} -Your API key enables full access to your Organization. Keep your API key private. If you believe your API key has been compromised, select the **Rotate API Key** button on this screen. Active implementations of your current API key will need to be reconfigured with the new key before use. +Your Organization API Key enables full access to your Organization. Keep your API key private. If you believe your API key has been compromised, select the **Rotate API Key** button on this screen. Active implementations of your current API key will need to be reconfigured with the new key before use. {% endcallout %} ### Bearer Access Tokens