Beginning with version 4.41.83 a password can be locked so that users who want to view or use it must enter a reason. Additionally, when someone enters this reason, an email message is sent to its password manager.
Locking/unlocking a password
Any user that can edit a password can lock it. To lock a password go to the password screen and click on the "Locking" button. The "Edit password locking" screen will be shown, and the locking state can be changed by checking or unchecking the "Lock password" checkbox:
When a password is locked a lock icon will appear before the password name, none of its data will be shown and no operation can be done on it. Instead, a button with the label "Enter reason to unlock" will appear. This is the password screen of a locked password:
And this is how the locked password looks like in lists:
Note: when a user locks a password, it will be unlocked for her for the remainder of her session.
Entering a reason to unlock the password
Any user with access to the password who wants to view or use it will have to unlock it by entering a reason. Note that here unlock means "unlock for the remainder of the session". The password will still have a locked status, but for the user who has entered a reason it will appear as unlocked.
Clicking on the "Enter reason to unlock" button will show a screen prompting for the reason:
When a password is unlocked the lock icon will still appear before the name but it will be "opened", all of its data will be shown and also operations can be done on it:
Unlocking a password with a reason will also generate two events:
- The unlocking will be logged with the action "Unlock password" and the reason in the "Additional data" field.
- An email notification will be sent to the password manager with the entered reason.
This email notification looks like this:
Remember that an unlocked password remains unlocked for the rest of the session of the user. If you want to permanently unlock it for everyone you'll have to click on the "Locking" button and uncheck the "Lock password" checkbox.
How locking affects import/export and the API
Before V6.x, the export procedure is not affected by the locking state of a password. That is, locked passwords will be exported as if they weren't locked. In V6.x locked passwords are only exported its name and project name. Also, you can't define a password as locked using the import function. You have to import it first and then lock it using the "Locking" button as explained before or using the API.
The API, starting at version 2, has full support for locking. In short:
- Locking/unlocking a password can be done using the API (PUT /passwords/ID/lock.json and PUT /passwords/ID/unlock.json).
- To view or use a locked password, a special header called "X-Unlock-Reason" must be supplied with a reason.
- Those methods that do not supply "X-Unlock-Reason" will fail with Forbidden or, if showing a password, only the name and project will be returned. Please refer to the specific methods in the docs to see each case.
- API v1 has no support for locking. Locked passwords are only shown the name and project and no operation can be done on them.
Here you have the corresponding documents: