Lockout recovery process
This page describes how to recover administrator access for Bitbucket Data Center 5.x and later. For releases prior to that, please refer to the documentation specific to that version.
As an administrator, you may find yourself locked out of Bitbucket and unable to log in. This situation can arise when all users are managed externally from Bitbucket, and it becomes unable to access those user directories for some reason, including:
- The external user directory server is not accessible (because the network is down, or the directory is down, or the directory has been moved to another IP address).
- Users are managed within a Jira application and the Application Link from Bitbucket to a Jira application has been accidentally deleted.
- The admin password has been forgotten or lost.
- The admin account is shaded by a remote account in an LDAP or Jira application that is connected to Bitbucket but which is unavailable.
Steps for Linux:
Edit the
<Bitbucket installation directory>\bin\_start-webapp.shfile and add the "-Datlassian.recovery.password=temporarypassword" value to theJVM_SUPPORT_RECOMMENDED_ARGSproperty. The property value must be non-blank, and should look like this when you've done that:# Occasionally Atlassian Support may recommend that you set some specific JVM arguments. # You can use this variable to do that. Simply uncomment the below line and add any required # arguments. Note however, if this environment variable has been set in the environment of the # user running this script, uncommenting the below will override that. # JVM_SUPPORT_RECOMMENDED_ARGS=-Datlassian.recovery.password=temporarypasswordHere we are using "
temporarypassword", but you should use your own value.If your password includes special characters like ! (exclamation mark), @ (at sign), # (pound sign), $ (dollar sign), % (percent sign), ^ (caret), & (ampersand), or * (asterisk), enclose the JVM argument within quotation marks. For example:
JVM_SUPPORT_RECOMMENDED_ARGS="-Datlassian.recovery.password=password-with-special-chars"- Start Bitbucket manually by running
<Bitbucket installation directory>\bin\start-bitbucket.sh. - Log in with the recovery admin username and the temporary password specified in Step 1.
In Bitbucket 8.19.4 and later 8.19.x bugfix releases, the recovery admin username is randomly generated and displayed in the Alerts section in the navigation bar. This username is also logged in the application logs. For example:Recovery mode is ON. Recovery admin username:.... For Bitbucket 8.19.0-8.19.3, the recovery admin username isrecovery_admin. - Repair your configuration. We strongly recommend that you do not perform other actions while Bitbucket is in recovery mode.
- Confirm your ability to log in with your usual admin profile.
- Shut down Bitbucket, remove the
atlassian.recovery.passwordargument from_start-webapp.sh, and restart Bitbucket as usual.
Steps for Windows: We've ended support for Bitbucket Server and Data Center hosting on Windows from 8.0. For lockout recovery process in Windows, see our 7.21 documentation.
Steps for Kubernetes
A Kubernetes environment doesn’t have a _start-webapp.sh file that can be edited to pass the recovery password. Therefore, you need to pass it as a JVM argument in a ConfigMap referenced by a StatefulSet. In most cases, the default ConfigMap is bitbucket-jvm-config.
You can check it in the following example:
kubectl edit configmaps -n <namespace> bitbucket-jvm-config -o yaml
apiVersion: v1
data:
additional_jvm_args: -Datlassian.recovery.password=<temp password> -XX:ActiveProcessorCount=8Then, you need to restart the StatefulSet:
kubectl rollout restart statefulset bitbucket -n <namespace>If the login page is disabled due to SSO restrictions, learn how to bypass SSO from How to enable auth_fallback functionality when using SSO in Bitbucket Data Center.