Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Account Ownership Verification


While this workflow focuses on disabling Two-factor Authentication on a account, it should also be used any time ownership of an account needs to be verified, such as for account changes.

2FA removal and other account actions can only be taken if the workflow below is successful.

Access by User Action

In many cases, users can regain access to their account using the following methods:

Entering a recovery code

Users can try and login using their saved two-factor recovery codes.

Generating new recovery codes via SSH

If a user didn't save their recovery codes, new ones can be generated with the command below via SSH if they've previously added an SSH key to their account. The new recovery codes can then be used at sign in. This option is presented to users in the Zendesk macro and the auto-response they'll receive if they chose Two-Factor Authentication (Account Recovery) as the problem type for the Zendesk ticket. If they cannot use this method then move on to the manual methods below.

ssh 2fa_recovery_codes

If a user has added an SSH key to their account but receives a Permission denied (publickey) error when using the command above, they may need to manually register their private SSH key using ssh-agent if they're using a non-default SSH key pair file path. Direct the user to our documentation for guidance on how to solve this.

Access with Support Intervention

If the user is unable to remove 2FA or otherwise regain access to their account using the above methods and responds with the need for further verification, then the user will need to provide evidence of account ownership before we can disable 2FA on their account.

If a user has lost their account recovery codes and has no SSH key registered, proving they own the account can be difficult. In these cases, please use the workflow below.


As part of access recovery, if 2FA removal is not involved, then skip the following steps and move on to the next section.

  1. Apply the "Account::2FA Removal SSH Info & Challenges" Macro
  2. The macro marks the ticket as "Pending"

If the user responds with the need for further verification (by answering the challenges)

  1. Using the Risk Factor Worksheet (internal only), determine the appropriate data classification level and the risk factor you have determined from customer's answers to the challenges.
    • For almost all cases, the originating email should be the same as the one listed on the account.
  2. Use the macro "Account::2FA::2FA Internal Note" It leaves an internal note on the ticket. Edit with the relevant admin link, your proposed data classification level, challenges and the risk factor.

  3. Request that your decision be peer-reviewed by another member of the team via Slack.

  4. For disabling 2FA: If you agree with the decision; log into your admin account and locate the username in the users table or by going to
    1. Under the account tab, click Edit, add an Admin Note, and save.
    2. On the account tab, click on Disable 2FA.
    3. Use the "Account::2FA::2FA Removal Verification - Successful" macro.
  5. In case you disagree, leave an internal note on the ticket stating your thoughts on what the risk factor should be and reply to the Slack conversation for further discussion. Once agreed, apply above step.

Note: This only applies if you think the challenges were passed, in case the user sends back very minimal information and it's clear it's not sufficient, reply asking for more information immediately after their response.

User Successfully Proves Account Ownership

  1. For other situations other than 2FA, please see Account Changes workflow.

User Fails to Prove Account Ownership

  1. If the user is unable to pass the selected challenges:
    1. Inform them that without verification we will not be able take any action on the account. For 2FA, use the Account::2FA::2FA Removal Verification - - Failed macro.
    2. Mark the ticket as "Solved"

GitLab Team Members

If the user is a GitLab employee, follow the below process:

  1. Perform steps for SSH key and recovery codes, if possible.
  2. Confirm authenticity of the request by contacting the employee via phone or video call.
  3. Add an Admin Note with relevant information.