bitwarden/help
1
0
Fork 0
mirror of https://github.com/bitwarden/help synced 2025-12-06 00:03:30 +00:00
Code Issues Releases Wiki Activity

CLI Auth & Personal API Key Details (#767)

Browse Source 
* cli auth & api key information

* round 2

* add back in 'lock'

* edits

* fix callout
This commit is contained in:
fred_the_tech_writer
2021-10-12 11:55:00 -04:00
committed by GitHub
parent 46ad5cac79
commit 9c469c3cf7
4 changed files with 75 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
_articles/miscellaneous/cli-auth-challenges.md
View File

@@ -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
```

99
_articles/miscellaneous/cli.md
View File

@@ -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 <method> --code <code>
```
See [Appendices &rarr; Enums](#enums) for `<method>` values.
{% endcallout %}
### Using an API key
See [Appendices &rarr; Enums](#enums) for Two-step Login `<method>` 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 <method> --code <code>
```
See [Appendices &rarr; Enums](#enums) for `<method>` 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 <passwordenv>` or `--passwordfile <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

17
_articles/miscellaneous/personal-api-key.md
View File

@@ -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`|