A shared account on one person's device
The passkey of a shared account ends up on the phone, or in the personal manager, of whoever created it. Their holiday, or their departure, becomes everyone's problem.
Passkeys
Passkeys your team can share, and a vault that opens with one
Teampass keeps the passkeys of other sites in its items, next to the passwords they replace: whoever can open the item can sign in with it, and the private key never leaves your server. Users can also sign in to Teampass itself with a fingerprint, a face, a PIN or a security key.
Passkeys were built for one person. Teams share accounts.
A passkey replaces a password with a key held by a device or by a personal password manager. That suits an account one person owns. It suits the supplier portal, the registrar or the social media account that four colleagues use much less well.
So shared accounts stay on passwords
Rather than depend on one colleague, the team declines the passkey the site offers and keeps the password in the vault, where everyone who needs it can reach it.
And the vault still opens with a password
The place that holds every credential is itself protected by what passkeys were meant to replace: something typed, which can be typed into the wrong page.
For the sites your team uses, and for Teampass itself
Teampass uses passkeys for two independent things, each with its own settings. Both are off until an administrator turns them on.
Passkeys of other sites
Teampass keeps the passkeys of third-party sites in its items, like it keeps their passwords, and the browser extension signs in with them. The server side is open-source; the extension is the paid add-on.
Signing in to Teampass
A passkey confirms, or replaces, the password of a Teampass account. It needs the open-source server, HTTPS and a browser that supports passkeys — no extension.
Turning one on does not turn the other on, and a passkey of one is never usable by the other.
The private key is created, kept and used on your server
A passkey kept in Teampass is not a file handed to each browser. The extension relays the request of the site; the server signs it and sends back the signature, nothing else.
-
Step 1
A site offers a passkey
A Teampass window opens in the browser. Choose the item to store the passkey in, or create a new one in a folder of your choice, then save.
-
Step 2
The server generates the key
An ECDSA P-256 key pair is generated on the Teampass server. Its private key is encrypted with a key of its own, itself encrypted for each user — the same scheme as item passwords.
-
Step 3
The site asks for it later
Choose the account and sign in. The extension relays the request, the server signs it for the site the passkey was created for, and only the signature comes back.
-
Step 4
The use is recorded
Passkey added, Passkey used and Passkey deleted are written to the item history with the site concerned, under the user the server signed for.
Everyone who can open an item can use its passkeys. A passkey saved in a shared folder signs in for every member of that folder, exactly like its password. One saved in a personal folder signs in for its owner only.
A passkey behaves like the item that holds it
- Folder rights, item restrictions and the recycle bin apply to passkeys as they do to passwords
- A read-only user of the folder can sign in with a passkey, but cannot save or delete one
- The item card lists its passkeys with the site, the account, the creation date and the last use
- A fingerprint next to the title marks the items that hold a passkey
- Passkeys follow their item when it is moved, and are never copied or exported
- New users receive the keys of the passkeys they can reach, and Restore missing sharekeys covers passkeys too
A passkey saved without your knowledge gets noticed. The user who saves a passkey is e-mailed the site, the account and the item, unless the administrator turns the notification off. A passkey added with a stolen session does not stay silent.
A second factor, or no password at all
A fingerprint, a face, a PIN or a security key confirms a Teampass sign-in instead of a code, and can replace the password entirely. The passkey is registered by the user and never leaves their device: Teampass only stores its public key.
As a second factor
After the login and the password, Teampass asks for the passkey. Where Google Authenticator or Duo is already required, the passkey is offered next to them and the user picks one.
Without a password
In passwordless mode, the login page shows Sign in with a passkey. The account is the one the chosen passkey belongs to: nothing has to be typed, and one click opens the browser dialog.
Offered, never imposed
An account without a passkey signs in exactly as before. There is no enrolment during sign-in: users add up to 20 passkeys from their profile, after confirming their password.
Adoption you can see
A badge on the Users page gives the number of sign-in passkeys of each account, and the administration dashboard counts the active accounts that hold one.
| Account | Sign-in without a password |
|---|---|
| Local account | Allowed |
| Directory (LDAP) or OAuth2 account | Refused: the passkey stays a second factor, because a sign-in without the directory password would bypass a directory that may have disabled the account |
| Account waiting for its keys, for a re-encryption or for a one-time code | Refused until that step is done with the password |
| Another second factor imposed, with Passwordless sign-in counts as MFA off | Refused: the password path goes through that factor |
A lost authenticator never locks anyone out for good. An administrator, or a manager of the account, revokes the passkey from the Users page, and the account goes back to its password, plus any other method it had.
What the server refuses to do
Each rule below is enforced by the server, whatever the extension or the browser asks for.
No endpoint returns the private key
The API signs on the server and sends back the signature only. The credential identifier is random and generated by Teampass, never supplied by the client.
Bound to its site
A passkey signs only for the site it was created for. A signature counter grows at each use, which lets a site detect a cloned passkey.
The vault's own passkey stays out of the vault
The server refuses to keep the passkey of its own sign-in page in an item: it would let everyone who can open that item sign in as its owner.
A password before a new passkey
An open session is not enough to add a sign-in passkey. Whoever finds one unattended cannot register a passkey of their own and keep signing in after the owner changed their password.
An encryption key that stays wrapped
A passwordless passkey carries an encrypted copy of the user's encryption key, opened by a secret only the authenticator can produce or, without PRF, by a key derived from the instance secret file. A setting refuses the second.
Refusals count, changes are logged
A refused passkey counts towards the account lockout like a wrong password. Additions, deletions and passwordless changes are logged, and the owner is e-mailed when a passkey is added.
Off by default, and yours to scope
The first setting is under Settings → API → Browser Extension, the others under Settings → MFA → Passkeys; the notification is on both tabs. The names below are the ones the settings pages show.
| Setting | Default | What it controls |
|---|---|---|
| Allow the browser extension to save passkeys | Off | Turns the passkeys of other sites on for the whole instance; each user can still turn it off in the extension |
| Notify users when a passkey is saved | On | E-mails the user who saved a passkey; covers both kinds of passkey and needs an e-mail server |
| Sign in with a passkey | Disabled | Disabled, as a second factor, or passwordless and as a second factor |
| Require PRF for passwordless sign-in | Off | Refuses the copy of the encryption key the server can open; turning it on deletes the copies already registered |
| Passwordless sign-in counts as MFA | On | When off, an account on which Google Authenticator or Duo is imposed must sign in with its password |
| Relying party ID | Empty | The domain the sign-in passkeys are bound to; empty means the host of the Teampass URL |
| Name shown when creating a passkey | TeamPass | Shown by the browser and the authenticator |
Choose the relying party ID before users register. Authenticators bind a passkey to that domain: changing it makes every registered sign-in passkey unusable. When passkeys exist, Teampass asks for a confirmation before saving a new value.
For the passkeys of other sites, the API rights of each user decide what the extension may do on their behalf: Read to sign in, Update to save or delete a passkey — on top of the right to edit the item, never beyond it.
What passkeys in Teampass do not do
Work without the server
The private key never leaves the server: a passkey kept in Teampass cannot be used while the server is down or unreachable, and it is not part of the offline export. Keep another way to sign in on every account it protects.
Import, export or survive an old backup
Passkeys stored elsewhere cannot be imported, and those kept in Teampass cannot be exported. Restoring a backup loses the passkeys saved since that backup, while the sites still expect them.
Satisfy every site
Sites that require attestation or device-bound passkeys, as some enterprise identity providers do, do not accept Teampass passkeys. Only ES256 passkeys are created, and the extension does not offer passkeys in the browser's autofill suggestions, nor inside frames.
Replace the directory password
LDAP and OAuth2 accounts use their passkey as a second factor only. An instance whose accounts all come from a directory gains nothing from the passwordless mode.
From switched off to a first passkey
-
Serve Teampass over HTTPS
Browsers only offer passkeys in a secure context. For the passkeys of other sites, also enable Require HTTPS for API requests: System Health warns while the API still accepts plain HTTP.
-
Turn on what you need
Allow the browser extension to save passkeys in Settings → API → Browser Extension, a mode for Sign in with a passkey in Settings → MFA → Passkeys, or both.
-
Save the first one
With the extension, accept the passkey a site offers and store it in an item. For Teampass itself, add one from Profile → Sign-in and security → Sign-in passkeys.
Both features arrived in 3.2.3.0 — see What's new. The passkeys of other sites need the browser extension 1.8.0 or later. Every setting, restriction and error message is described in the Passkeys documentation.
Straight answers
Are the two passkey features linked?
No. Keeping the passkeys of other sites and signing in to Teampass with a passkey each have their own settings. Turning one on does not turn the other on, and a passkey of one is never usable by the other.
Where is the private key of a passkey kept in Teampass?
On your Teampass server, and nowhere else. It is generated there, encrypted like an item password, and used there. No endpoint returns it: the browser extension only relays the request of the site and receives a signature in return.
Who can sign in with a passkey kept in an item?
Everyone who can open the item. In a shared folder, that is every user with access to the folder, minus those excluded by an item restriction; in a personal folder, its owner only. A read-only user of the folder can sign in with the passkey, but cannot save or delete one.
Do I need the browser extension?
For the passkeys of other sites, yes: it is the extension, version 1.8.0 or later, that answers a site’s passkey request in the browser, and the extension is a paid add-on with a free trial. Signing in to Teampass itself with a passkey needs nothing but the open-source server and a browser.
What happens when the Teampass server cannot be reached?
A passkey kept in Teampass cannot be used, because its private key never leaves the server. When the server takes more than 5 seconds to answer, or cannot be reached, the browser’s own passkey window opens instead. Keep another way to sign in — a password, recovery codes — on every account such a passkey protects.
Can I import the passkeys I already have?
No. Passkeys already stored in a browser, a phone or another password manager cannot be imported, and the passkeys kept in Teampass cannot be exported.
Does enabling sign-in passkeys force my users to enrol?
No. Passkeys are offered, never imposed. An account without a passkey signs in exactly as before, and there is no enrolment during sign-in: users register a passkey from their profile, whenever they choose to.
What if a user loses the phone or the key that holds their passkey?
An administrator, or a manager of that account, revokes the passkey from the Users page. The revocation takes effect at once, and the account goes back to its password, plus any other method it had.
Can LDAP or OAuth2 accounts sign in without a password?
No. Signing in without the directory password would bypass a directory that may have disabled the account, so these accounts use their passkey as a second factor. Passwordless sign-in is for local accounts.
How can a sign-in without a password decrypt anything?
Every item is encrypted with the user’s key, and that key is protected by their password. A passkey used for passwordless sign-in therefore carries a second, encrypted copy of that key, opened either by a secret only the authenticator can produce (PRF) or, for the authenticators without PRF, by a key derived from the instance secret file, which is outside the database. Require PRF for passwordless sign-in refuses the second kind.
Can Teampass keep the passkey that signs in to Teampass?
No. The server refuses to save or to use such a passkey in an item, and the extension leaves the pages of its own Teampass server to the browser: an item holding it would let everyone who can open it sign in as its owner. Register that passkey on another authenticator — Windows Hello, a phone, a security key.
Is it enabled by default?
No. An administrator turns on Allow the browser extension to save passkeys for the passkeys of other sites, and chooses a mode in Sign in with a passkey for Teampass itself. Both need Teampass 3.2.3 or later. Serve it over HTTPS first: sign-in passkeys do not work without it.
Keep the passkey where the password already is.
Install Teampass, turn passkeys on, and let the next shared account move off its password.