# About Trusted Devices

SSO with trusted devices allows users to [authenticate using SSO](https://bitwarden.com/help/about-sso/) and decrypt their vault using a device-stored encryption key, eliminating the need to enter a master password. A trusted device is a Bitwarden app, like an instance of the browser extension or mobile app, that has been approved for use of passwordless sign-in [by the user](https://bitwarden.com/help/add-a-trusted-device/) or [by an administrator](https://bitwarden.com/help/approve-a-trusted-device/). Each Bitwarden app would be a separate trusted device, with a separate approval, even if they're on the same computer or smartphone.

SSO with trusted devices gives business end users a passwordless experience that is also zero-knowledge and end-to-end encrypted. This prevents users from getting locked out due to forgotten master passwords and allows them to enjoy a streamlined login experience.

## Start using trusted devices

To get started using SSO with trusted devices:

1. [Setup SSO with trusted devices](https://bitwarden.com/help/setup-sso-with-trusted-devices/) for your organization.
2. Provide administrators with information on [how to approve device requests](https://bitwarden.com/help/approve-a-trusted-device/).
3. Provide end-users with information on [how to add trusted devices](https://bitwarden.com/help/add-a-trusted-device/).

## How it works

The following tabs describe encryption processes and key exchanges that occur during different trusted devices procedures:

### Onboarding

When a new user joins an organization, an **Account Recovery Key** ([learn more](https://bitwarden.com/help/account-recovery/)) is created by encrypting their account encryption key with the **Organization Public Key**. Account recovery is required to enable SSO with trusted devices.

The user is then asked if they want to remember, or trust, the device. When they opt to do so:

![Create a trusted device](https://bitwarden.com/assets/2o9o8L0JZMvWZYJvfKGMzj/b7cab59682862c8e782331ed6a2ef9d9/td-create.png)
*Create a trusted device*

1. A new **Device Key**is generated by the client. This key never leaves the client.
2. A new RSA key pair, called the **Device Private Key**and **Device Public Key**, is generated by the client.
3. The user's account encryption key is encrypted with the unencrypted **Device Public Key** and the resultant value is sent to the server as the **Public Key-Encrypted User Key**.
4. The **Device Public Key**is encrypted with the user's account encryption key and the resultant value is sent to the server as the **User Key-Encrypted Public Key**.
5. The **Device Private Key** is encrypted with the first **Device Key** and the resultant value is sent to the server as the **Device Key-Encrypted Private Key**.

The **Public Key-Encrypted User Key** and **Device Key-Encrypted Private Key** will, crucially, be sent from server to client when a login is initiated.

The **User Key-Encrypted Public Key** will be used should the user need to rotate their account encryption key.

### Logging in

When a user authenticates with SSO on an already-trusted device:

![Use a trusted device](https://bitwarden.com/assets/61SSa6ITlRaICIUoCzEiVp/746cf3ba3005b4118d20319e894c47c7/td-use.png)
*Use a trusted device*

1. The user's **Public Key-Encrypted User Key**, which is an encrypted version of the account encryption key used to decrypt vault data, is sent from the server to the client.
2. The user's **Device Key-Encrypted Private Key**, the unencrypted version of which is required to decrypt the **Public Key-Encrypted User Key**, is sent from the server to the client.
3. The client decrypts the **Device Key-Encrypted Private Key**using the **Device Key**, which never leaves the client.
4. The now-unencrypted **Device Private Key**is used to decrypt the **Public Key-Encrypted User Key**, resulting in the user's account encryption key.
5. The user's account encryption key decrypts vault data.

### Approving

When a user authenticates with SSO and opts to decrypt their vault with an un-trusted device (i.e. a **Device Symmetric Key**does not exist on that device), they are required to choose a method of approving the device and optionally trusting it for future use without further approval. What happens next depends on the selected option:

- **Approve from another device**: 

 1. The process documented [here](https://bitwarden.com/help/log-in-with-device/#how-it-works/) is triggered, resulting in the client having obtained and decrypted the account encryption key.
 2. The user can now decrypt their vault data with the decrypted account encryption key. If they have chosen to trust the device, trust is established with the client as described in the **Onboarding**tab.
- **Request admin approval**:

 1. The initiating client POSTs a request, which includes the account email address and a unique **auth-request public key**ª, to an Authentication Request table in the Bitwarden database.

![User requests admin approval (Step 1)](https://bitwarden.com/assets/1CgwXVCrjssDwsz2Aie4mV/aac6c3975c9a8d225074268c093cadc3/2025-04-30_09-33-37.png)
*User requests admin approval (Step 1)*
 2. Administrators can [approve or deny the request](https://bitwarden.com/help/approve-a-trusted-device/) on the Device approvals page.
 3. When the request is approved by an administrator, the approving client encrypts the user's account encryption key using the **auth-request public key** enclosed in the request.
 4. The approving client then PUTs the encrypted account encryption key to the Authentication Request record and marks the request fulfilled.

![Admin approves auth request (Steps 3-4)](https://bitwarden.com/assets/4Y9q6Y3KmLskDaqfF03YmJ/8a99742b2bf8e7394cb0988495dc13b0/2025-04-30_09-34-10.png)
*Admin approves auth request (Steps 3-4)*
 5. The initiating client GETs the encrypted account encryption key and **locally **decrypts it using the **auth-request private key**.

![User receives admin approval (Step 5)](https://bitwarden.com/assets/7LNcFuhupPeR4DJhg2k4po/10ae5da219f1e5338e5cdf6554655e9f/2025-04-30_09-34-28.png)
*User receives admin approval (Step 5)*
 6. Using the decrypted account encryption key, trust is established with the client as described in the **Onboarding**tab.

ª - **Auth-request public** and **private keys** are uniquely generated for each passwordless login request and only exist for as long as the request does. Unapproved requests will expire after 1 week.

- **Approve with master password**: 

 1. The users's account encryption key is retrieved and decrypted as documented in the [Authentication and decryption](https://bitwarden.com/help/bitwarden-security-white-paper/#authentication-and-decryption/) section of the security whitepaper.
 2. Using the decrypted account encryption key, trust is established with the client as described in the **Onboarding**tab.

### Key rotation

> [!NOTE] Which TDE users can rotate an enc key
> Only users who have a master password can rotate their [account encryption key](https://bitwarden.com/help/account-encryption-key/). [Learn more](https://bitwarden.com/help/about-trusted-devices/#impact-on-master-passwords/).

When a user rotates their [account encryption key](https://bitwarden.com/help/account-encryption-key/), during the normal rotation process:

1. The **User-Key Encrypted Public Key** is sent from the server to the client, and subsequently decrypted with the old account encryption key (a.k.a. **User Key**), resulting in the **Device Public Key**.
2. The user's new account encryption key is encrypted with the unencrypted **Device Public Key** and the resultant value is sent to the server as the new **Public Key-Encrypted User Key**.
3. The **Device Public Key**is encrypted with the user's new account encryption key and the resultant value is sent to the server as the new **User Key-Encrypted Public Key**.
4. The Public Key-Encrypted User Key is then re-shared with each trusted device.

### Keys used for trusted devices

This table provides more information about each key used in the procedures described above:

| Key | Details |
|------|------|
| Device Key | AES-256 CBC HMAC SHA-256, 512 bits in length (256 bits for key, 256 bits for HMAC) |
| Device Private Key & Device Public Key | RSA-2048 OAEP SHA1, 2048 bits in length |
| Public Key-Encrypted User Key | RSA-2048 OAEP SHA1 |
| User Key-Encrypted Public Key | AES-256 CBC HMAC SHA-256 |
| Device Key-Encrypted Private Key | AES-256 CBC HMAC SHA-256 |

### Impact on master passwords

While SSO with trusted devices eliminates the need for a master password, it doesn't in all cases eliminate the master password itself:

- If a user is onboarded **before** SSO with trusted devices is activated, their account will retain its master password.
- If a user is onboarded **after** SSO with trusted devices is activated and they select **Log in**→**Enterprise SSO**from the organization invite for [JIT provisioning](https://bitwarden.com/help/sso-faqs/#q-how-does-login-with-sso-work-for-new-users-just-in-time/), their account will not have a master password. Should you change to the master password [member decryption option](https://bitwarden.com/help/sso-decryption-options/), these users will be prompted to create a master password when they log in as long as they are still a member of the organization ([learn more](https://bitwarden.com/help/setup-sso-with-trusted-devices/)).

> [!WARNING] Accounts without MPs & TDE
> For member accounts that do not have master passwords as a result of [SSO with trusted devices](https://bitwarden.com/help/about-trusted-devices/):
> 
> - [Removing them from your organization](https://bitwarden.com/help/remove-users/#remove-members-from-an-organization/) eliminates all access to their Bitwarden account unless they were previously assigned a master password using [account recovery](https://bitwarden.com/help/account-recovery/) and they log in with that master password at least once before being removed.
> 
> These users will not be able to re-join your organization unless the above steps are taken **before** they are removed from the organization. If they aren't, each removed user will be required to [delete their account](https://bitwarden.com/help/delete-your-account/#delete-an-individual-account/) and be issued a new invitation to create an account and join your organization.
> - [Revoking access to the organization](https://bitwarden.com/help/revoke-users/), but not removing them from the organization, will still allow them to log in to Bitwarden and access **only** their individual vault.
- If a user account is recovered using [account recovery](https://bitwarden.com/help/account-recovery/), their account will necessarily be assigned a master password. A master password cannot currently be removed from an account once it has one, so to avoid this outcome we recommend that you (i) instruct the user to export their data to a backup, (ii) completely delete the lost account, (iii) ask the user to [re-onboard to your organization using trusted devices](https://bitwarden.com/help/add-a-trusted-device/) and (iv) once they've done so instruct them to import their backup.

### Impact on other features

Depending on whether a master password hash is available in memory for your client, which is dictated by how your client application is initially accessed, it may exhibit the following behavior changes:

| Feature | Impact |
|------|------|
| Verification | There are a number of features in Bitwarden client applications that ordinarily require entry of a master password in order to be used, including [exporting](https://bitwarden.com/help/export-your-data/) vault data, changing [two-step login settings](https://bitwarden.com/help/setup-two-step-login/), retrieving [API keys](https://bitwarden.com/help/personal-api-key/), and more. If the user doesn't use a master password to access the client, **all these features**will replace master password confirmation with email-based TOTP verification. |
| Vault lock/unlock | Under ordinary circumstances, a [locked vault can be unlocked](https://bitwarden.com/help/vault-timeout/#session-timeout-action/) using a master password. If the user doesn't use a master password to access the client, locked client applications can only be unlocked with a [PIN](https://bitwarden.com/help/unlock-with-pin/) or with [biometrics](https://bitwarden.com/help/biometrics/). If neither PIN nor biometrics are enabled for a client application, the vault will always log out instead of lock. Unlocking and logging in will **always**require an internet connection. |
| Master password re-prompt | If the user does not unlock their vault with a master password, [master password re-prompt](https://bitwarden.com/help/managing-items/#protect-individual-items/) will be disabled. |
| Changing email address | Users who [do not have master passwords](https://bitwarden.com/help/about-trusted-devices/#impact-on-master-passwords/) **will not** be able to change their email address. |
| CLI | Users who [do not have master passwords](https://bitwarden.com/help/about-trusted-devices/#impact-on-master-passwords/) **will not** be able to access Password Manager CLI. |