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. When someone enters this reason, an email message is sent to its password manager.
Since version 7.79.190 locked passwords can optionally be unlocked only with the permission of the password manager.
Since version 7.80.192 locked passwords can optionally be unlocked only with the permission of the password manager or all the users who have manage permission on the password.
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 after 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:
If the "Requires permission to unlock" check is checked in addition to the "Lock password" one, then instead of having to enter a reason to unlock the password, the user wishing to unlock it will have to request permission to do so to the password manager. A locked password that requires permission to unlock will be shown this way:
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 after 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. Since v. 7.80.192 this notification will be sent to all the users with manage permission if when configuring locking it's specified so.
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.
Requesting permission to unlock the password
Since v. 7.80.192 a locked password can be configured to "Require permission to unlock" with two additional options:
- Request permission to "The password manager".
- Request permission to "All the users with manage permission on the password".
Request permission to "The password manager"
If a locked password requires permission to be unlocked from the password manager, a user whishing to unlock it must click on the "Request Permission to Unlock" button. When this happens the following screen appears:
This screen allows the user that wants to unlock the password to enter a reason for doing so and, when the blue "Request Permission to Unlock" button is clicked, an email is sent to the password manager so that he/she can grant or revoke permission to unlock. Specifically this is the email that the password manager receives:
The password manager must then click on "Click here to grant or revoke the permission to unlock this password for the user", which will bring up the following screen in Team Password Manager to let him/her grant or revoke permission to unlock:
When the password manager grants permission to unlock the password, the requester will receive an email message with a link to unlock and access the password, like this one:
When the requester clicks on "Click here to unlock the password and access it", the password will be unlocked and the user will be able to access it (for the remainder of the session). Also, an email will be sent to the password manager notifying that the requester has unlocked the password.
If, on the other hand, the password manager revokes permission to unlock the password, an email will be sent to the requester notifying him/her of this decision, and he/she will not be able to unlock the password.
Notes:
- If the user requesting permission to unlock is the password manager, it makes no sense to send messages back and forth and grant/revoke permissions. In this case, the user will just have to enter the reason to unlock the password.
- If the password manager is not valid (where here valid means that the manager exists, with a role that is not Read only, not API only and active), permission will be sent to the password's project project manager. If the project manager is not valid either, a message informing of this will be shown.
- Admin users do also have to enter the reason to unlock a password or request permission to unlock to the password manager.
Request permission to "All the users with manage permission on the password"
If a locked password is configured as "Request permission to All the users with manage permission on the password", the process is the same as the "Request permission to The password manager" one, except that in this case the request is sent to multiple recipients: any user with manage permission on the password. In this case, even the main password manager needs to request access.
The unlocking screen in this case looks like this:
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 support for locking (reason based). 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.
v. 7.79.190
Locked passwords that are permission based cannot be used with the API. In this case if the "X-Unlock-Reason" header is supplied a "409 Conflict" error with the message "Cannot unlock a password that requires permission to unlock" will be returned.
v. 7.80.192
Locked passwords that are permission based can only be accessed (any operation) by the main password manager, entering a reason. Other users cannot access the password using the API. In this case if the "X-Unlock-Reason" header is supplied a "409 Conflict" error with the message "Cannot unlock a password that requires permission to unlock" will be returned.
v. 7.82.196
There's a config.php parameter, SEND_UNLOCKING_NOTIFICATIONS_API, that controls whether the affected managers receive the unlocking notification (set to TRUE) or not (set to FALSE). The default is TRUE (send the notifications). Example: define('SEND_UNLOCKING_NOTIFICATIONS_API', FALSE);
Here you have the corresponding API documents:
