How to recover or reset 2FA Authentication in Jira
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
As mentioned in the official documentation for "Manage two-step verification", it is possible to disable the two-step authentication verification for an user if the access to the app and/or the recovery code are lost and the user is locked out of the application.
This KB aims to add more details to the process of removing, recovering and ensuring that the user regain the application access.
ℹ️ Manage two-step verification for your Atlassian account - Recovery unenrollment
Solution
REST API
As mentioned in the official doc:
Recovery unenrollment
In case a user has lost their recovery key, you can use a special REST endpoint to disable two-step verification for that user.
The endpoint is accessible for system admins only via the REST API to provide an unenrollment option when a user can’t disable two-step verification on their own.
Due to security reasons, it requires the system admin to have the two-step verification set up with TOTP.
As a system admin, you can’t disable two-step verification via the REST API for yourself.
Using cURL to disable the 2FA verification for a specific user:
Example cURL:
1
2
3
4
5
curl --request DELETE \
--url 'http://{baserURL}/rest/tsv/1.0/totp/unenroll/user/{username}>' \
--header 'Authorization: Bearer <api_token>' \
--header 'Content-Type: application/json'
--data '{"totpCode":"<totp_code>"}'⚠️ The 6-digit "<totp_code>" needs to be manually generated in admin's authenticator app, added to the curl parameters and used within the 30 seconds timeout of the authenticator app.
✅ A 204 status response indicates the success without any response message from the server.
Database
The steps outlined on this article are provided AS-IS. This means we've had reports of them working for some customers — under certain circumstances — yet are not officially supported, nor can we guarantee they'll work for your specific scenario.
You may follow through and validate them on your own non-prod environments prior to production or fall back to supported alternatives if they don't work out.
We also invite you to reach out to our Community for matters that fall beyond Atlassian's scope of support!
Alternatively, it's also possible to query the recovery code for the affected user in the database, allowing the user to regain its access using the recovery features in the UI:
Query to get the user's RECOVERY CODE
1
2
3
4
5
6
7
8
SELECT totp."RECOVERY_CODE", au.lower_user_name, totp."USER_KEY"
FROM "AO_ED669C_TOTP_USER_ENROLLMENT" totp
JOIN app_user au ON au.user_key = totp."USER_KEY"
WHERE "USER_KEY" = (
SELECT user_key
FROM app_user
WHERE lower_user_name = LOWER('<username>')
);ℹ️ Follow the official documentation to learn how to use the recovery code to regain the user access in order to register a new app authentication or to turn off the 2FA settings in the UI.
⚠️ Important notice ⚠️
Manipulating the database directly is not supported by Atlassian! Proceed at your own risk!
Remove the affected user's 2FA settings:
It's also possible to remove the user's 2FA credentials and parameters entry in the database, effectively, disabling the two-step authentication settings of that user:
Always back up your data before making any database modifications. If possible, test any alter, insert, update, or delete SQL commands on a staging server first.
Query to delete the user's 2FA parameters
1
2
3
4
5
6
DELETE FROM "AO_ED669C_TOTP_USER_ENROLLMENT"
WHERE "USER_KEY" = (
SELECT "user_key"
FROM "app_user"
WHERE "lower_user_name" = LOWER('<username>')
);Was this helpful?