# Logging in ### First Login on a New Device To login to Commander for the first time, click the Keeper Commander icon or open a shell and type: ``` keeper shell ``` If you are using the US data center, just type `login` to start the login process. The Keeper Commander CLI will default to the US data center. To change regions, use the `server` command. For example, to switch to the EU data center, type: ``` server EU ``` Login to Commander with the `login` command: ``` login my@company.com ``` #### **Device Approval** Depending on your setup, you might need to approve the device. Several methods are available. ``` Not logged in> login me@company.com Device Approval Required Approve by selecting a method below: "email_send" to send email "email_code=
" to validate verification code sent via email
        "keeper_push" to send Keeper Push notification
        "2fa_send" to send 2FA code
        "2fa_code=" to validate a code provided by 2FA application
        "approval_check" check for device approval
Type your selection: 
```

* If you wish to approve via email:
  * Type `email_send` or `es`
  * Enter the security code with `email_code=`
* If you wish to approve via Keeper Push:
  * Type `keeper_push`
  * Approve via push
  * Then type `approval_check`
* If you wish to approve via 2fa code:
  * Input `2fa_send`
  * Then input `2fa_code=`

***

### Logging in **with a Master Password**

After device approval, you will immediately move to the login process, or if you previously approved the device, this will be the first step.

#### **Master Password Login Example** 

Not logged in> login
...      User(Email): yourname@email.com
Logging in to Keeper Commander
Enter password for yourname@email.com
Password: *********

Successfully authenticated with Login V3 (Password)
Syncing...
Decrypted [23] record(s)
My Vault>


***

### Logging in With 2FA

If you have 2FA enforced on your account, you will be required to pass the 2FA step before logging in with a Master Password. Your login flow in commander will follow the same rules you have for logging into the Vault.

```
Not logged in> login
...      User(Email): yourname@email.com
This account requires 2FA Authentication
  1. TOTP (Google and Microsoft Authenticator)  
  2. WebAuthN (FIDO2 Security Key)
  q. Quit login attempt and return to Commander prompt
Selection: 1
```

Each 2FA method that is enabled will have a number next to it.  

In this example, only TOTP is enabled, so `1` would need to be entered, followed by the TOTP code. Enter the corresponding number to proceed:

```
Selection: 1

Enter 2FA Code or Duration: 2fa_duration=forever
Enter 2FA Code or Duration: 123456
```

By default, Keeper Commander prompts for 2FA code on every login. To store 2FA authentication for this device either for 30 days or forever, type one of the following before entering the code:

* `2fa_duration=30_days` to prompt for 2FA every 30 days, or...
* `2fa_duration=forever` to never prompt again on this device

***

### Logging in with Biometric Authentication

If biometric authentication is configured on your device, you can use Windows Hello or Touch ID to log in to Keeper Commander. This allows you to bypass both the Master Password and two-factor authentication (2FA) for a faster, secure login experience.

{% tabs %}
{% tab title="Windows" %}
For Windows users, ensure Windows Hello is configured:

* Navigate to Settings > Accounts > Sign-in options > Windows Hello
* Set up Face recognition, Fingerprint, or PIN
  {% endtab %}

{% tab title="macOS" %}
For macOS users, ensure Touch ID is enabled:

* Navigate to System Preferences > Touch ID & Password
* Add your fingerprint(s) to the system
  {% endtab %}
  {% endtabs %}

#### **Register Biometric Authentication**

First, login to Keeper Commander with your Master Password (or SSO), then register biometric authentication:

```bash
# Login with your Master Password or SSO first
Not logged in> login
...      User(Email): yourname@email.com
Logging in to Keeper Commander
Enter password for yourname@email.com
Password: *********

# Then register biometric authentication
My Vault> biometric register

# Or you can also provide a friendly name for your biometric credential:
My Vault> biometric register --name "My MacBook"
Adding biometric authentication method: My MacBook
Please complete biometric authentication...
```

Biometric authentication prompt (fingerprint or Face ID) will be displayed.

{% tabs %}
{% tab title="Windows" %}
Register by authenticating with your fingerprint or faceID when prompted by the system.


{% endtab %}

{% tab title="macOS" %}
Register by authenticating with your fingerprint when prompted by the system.


{% endtab %}
{% endtabs %}

With successful fingerprint or faceID authentication the registration will be completed:

{% code overflow="wrap" %}

```bash
Biometric authentication completed successfully!

Success! Biometric authentication "My MacBook Touch ID" has been registered.
Please register your device using the "this-device register" command to set biometric authentication as your default login method.
```

{% endcode %}

#### Device Registration

To use biometric authentication as your default login method, you must register your device

```bash
My Vault> this-device register
```

#### Login Example with Biometric Authentication

Once biometric authentication and device are registered, your login will look like this:

{% embed url="" %}

```
Not logged in> login
...      User(Email): yourname@email.com
Logging in to Keeper Commander

Attempting biometric authentication...
Press Ctrl+C to skip biometric and default login method
Successfully authenticated with Biometric Login!
Syncing...
Decrypted [1] record(s)
My Vault> 
```

**Managing Biometric Credentials**

Command Description
biometric list List all registered biometric credentials
biometric update-name Update the friendly name of a biometric credential
biometric unregister Remove biometric authentication from current device
biometric verify Test biometric authentication without logging in

***

### Logging In with Enterprise SSO (SAML 2.0)

If SSO is configured for your Keeper enterprise account, the following screen will appear for users that login to Commander:

{% code overflow="wrap" %}

```
Not logged in> login
...      User(Email): yourname@email.com
Logging in to Keeper Commander

SSO Login URL:
https://keepersecurity.com/api/rest/sso/saml/login/xxx

Navigate to SSO Login URL with your browser and complete login.
Copy a returned SSO Token into clipboard.
Paste that token into Commander

  a. SSO User with a Master Password
  c. Copy SSO Login URL to clipboard
  o. Navigate to SSO Login URL with the default web browser
  p. Paste SSO Token from clipboard
  q. Quit SSO login attempt and return to Commander prompt
  
Selection:
```

{% endcode %}

To login to Commander using SSO, you will need to paste a token provided by the SSO provider from your web browser into Commander.  To receive the SSO token, follow these steps:

#### **SSO Login Using Default Browser**

To have Commander automatically open the default browser to the SSO Connect page, enter "o" in the SSO selection and hit `Enter`

The default browser for your system will open to the SSO Connect page.

{% hint style="info" %}
Depending on your operating system, settings, and administrator privileges, Commander may be unable to open the web browser, in this case use the following option to open the SSO Connect screen.
{% endhint %}

#### **SSO Login Using Pasted Token**

You can copy the URL to your SSO's logins screen from the SSO Connect text in Commander, or enter "c" in the SSO selection and hit `Enter` to copy the URL to your clipboard.

```
SSO Login URL:
https://keepersecurity.com/api/rest/sso/saml/login/xxx
```

Once the URL is copied, paste it into a web browser to navigate to the SSO Connect page.

After a successful SSO login, the web page will show a yellow "Copy" button.  Click the button to copy the token.

![SSO Login success screen](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FLtlzlTvOklQoOP4Cn9js%2FScreen%20Shot%202022-07-15%20at%206.01.11%20PM.png?alt=media\&token=b58d0065-79d9-4343-956c-3bb299eca687)

#### Paste the SSO Token

Once the token has been copied, go back to Commander to complete the SSO login.

In Commander enter **"p"** in the SSO selection screen and hit `Enter` to paste the token from your clipboard into Commander and complete SSO login.



What if There is No "Copy login token" Button?

In some cases, the "Copy login token" button may not appear.  This depends on your SSO setup and Commander version.  In this case, the SSO token will need to be manually copied from the web page source.

The page will remain in a loading state (with spinning icon) to give you time to find and copy the token.  Though the spinning icon appears to be loading, the page will not change.

Once you have opened the SSO Connect page in the browser, follow these instructions to copy the SSO token:

Right click the web page and select "View Page Source"  



With the page source open, search for "var token" and copy the token that follows that text. 

Be sure to copy all text between the quotation marks (") without copying the quotation marks themselves. Note that the token is longer than the page shows.

There are two possible formats that the token could have for SSO login

**The token is a long quoted string**

      `var token = "aQwD`h\&r`[...]"`

In this case copy everything within the quotation marks



#### **The token is a json object**

   `var token = {'result':'success', 'password':"d8!xe3[...]"}`

in this case, copy the entire object including the curly brackets



Once the token has been copied, go back to Commander to complete the SSO login.

In Commander enter "p" in the SSO selection screen and hit `Enter` to paste the token from your clipboard into Commander and complete SSO login.



***

### Device Approval with SSO Login

If device approval is turned on for your account, the device approval selection will be shown after the first SSO login.

```
Approve this device by selecting a method below:
  1. Keeper Push. Send a push notification to your device.
  2. Admin Approval. Request your admin to approve this device.
  r. Resume SSO login after device is approved.
  q. Quit SSO login attempt and return to Commander prompt.
Selection: 
```

Enter your selection and hit `Enter` to continue with device approval. 

1 : Approve with Keeper Push

2 : Approve with Admin Approval

r : Resume SSO login after the device has been approved 

 See [First Login on a New Device section](#first-login-on-a-new-device) for more details on device approval.

### Use a Master Password with SSO Login

Customers who normally login to their Keeper Vault using Enterprise SSO Login (SAML 2.0) can also login to Keeper Commander using a Master Password. To make use of this capability, it must be enabled by the Keeper Administrator and then configured by the user. The steps are below:

#### **Login to the Keeper Admin Console**

As the admin, login to the Keeper Admin Console as you normally do.

#### **Enable SSO Master Password Policy**

For the User/Role who will be accessing Keeper Commander, open the Role Enforcement Policy setting screen. Enable the option "Allow users who login with SSO to create a Master Password"

![SSO Master Password Policy](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-Mel7nEasV2-9PcLt28R%2F-MelAMU5H8NOjViHwkEl%2FScreen%20Shot%202020-12-24%20at%208.54.50%20AM.png?alt=media\&token=986e1183-a395-49ef-b472-fed9162bac13)

#### **Login to the End-User Vault using SSO**

As the user who will be using Commander, login to the Keeper Web Vault or Keeper Desktop app with your SSO provider as you normally do.

#### **Create a Master Password**

Visit the Settings > General screen and setup a Master Password

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXOXEifAmpyvNVL1to%2F-Mel7nEasV2-9PcLt28R%2F-MelBP0BL3ei6D0pxshE%2FScreen%20Shot%202021-07-16%20at%202.20.19%20PM.png?alt=media\&token=b43c1f01-0acd-45f3-96bf-56c3ea0b5022)

After the Master Password is created, you are now able to login to Keeper Commander.

#### Optional: Force SSO Master Password Login in Configuration File

Add the following line to your configuration file.

```
{ ...
    "sso_master_password": true,
...}
```

***

### Logging in with a Proxy

If your network configuration requires using a proxy server you can use the `proxy` command before logging in.

{% code overflow="wrap" %}

```
My Vault> proxy -h                                                                                                                              
usage: proxy [-h] [-a {list,add,remove}] [schema://[user:password@]host:port]

Sets proxy server

positional arguments:
  schema://[user:password@]host:port
                        "add": proxy address. Schemas are "socks5h", "http", "socks4", etc

optional arguments:
  -h, --help            show this help message and exit
  -a {list,add,remove}, --action {list,add,remove}
                        action
```

{% endcode %}

***

### Persistent Login Sessions ("Stay Logged In")

Commander can be configured to stay logged in between sessions, and you can also configure how long the device will remain logged in without activity. This feature is referred to as "**persistent login**" or "Stay **Logged In**" in the Keeper Vault UI.

Using a persistent login session will allow you to execute Commander scripts without being prompted for authentication. Since this setting applies to all devices for that particular account, it also enables "stay logged in" across the web vault, mobile apps and desktop apps associated to that user.

Use the `this-device` command to set your preferences.

Example:

```
My Vault> this-device
                     Device Name: Commander CLI on macOS
                Data Key Present: missing
                 IP Auto Approve: OFF
                Persistent Login: OFF
           Device Logout Timeout: 1 hour
       Enterprise Logout Timeout: 7 days
        Effective Logout Timeout: 1 hour
                     Is SSO User: True
```

 To enable "Stay Logged In" so that you're not prompted for authentication, use these commands:

```
this-device persistent-login on 
this-device register
```

If persistent login is enabled, you won't be prompted to authenticate the next time you run Commander:

```
user@mycomputer ~ % keeper shell
Logging in to Keeper Commander
Successfully authenticated with Persistent Login
```

{% hint style="warning" %}
Activating persistent login ("stay logged in") for a login ID affects all devices that you use with Keeper. When persistent login is enabled, you need to ensure that the local device is protected from access, and you need to ensure that the `config.json` file on the local device is secured.
{% endhint %}

To set the inactivity logout timer to a certain number of minutes. For example:

this-device timeout 600


If 2FA is configured on the account, you may need to also set up the 2FA frequency. For example, to set the frequency to not prompt again on this device:

```
this-device 2fa_expiration forever
```

The resulting configuration file is typically stored in the home directory under `.keeper/config.json` in the local device. It's important to note that the configuration must be only used by one device. If you login to Commander using that configuration on a second device, both sessions will be revoked and persistent login will break. This is by design, to prevent a configuration from being used in multiple locations. If you plan to use the configuration on another device, such as a container or a server in the cloud, delete it locally immediately after creation.

### Working with Commander

{% embed url="" %}
Keeper Commander – Accessing and Working with Your Vault
{% endembed %}
Command	Description
`biometric list`	List all registered biometric credentials
`biometric update-name`	Update the friendly name of a biometric credential
`biometric unregister`	Remove biometric authentication from current device
`biometric verify`	Test biometric authentication without logging in