2FA Removal

Overview

This workflow focuses on disabling Two-factor Authentication (2FA) on a GitLab.com account. The general principles for authenticating a request are covered in our account verification workflow.

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

Related topics

GitLab Team Members

If the user is a GitLab team member, have them contact IT Ops.

2FA removal within GitLab

Self Service 2FA removal

In most cases, users can disable 2FA themselves and regain access to their accounts using one of the documented methods.

As of August 2020, Support will not intervene for free users if self-service methods do not work for them.

Enterprise Owner 2FA removal for Enterprise users

A top-level group owner can disable 2FA for any enterprise user who is also a group member. A user is automatically claimed as an Enterprise User if the group has a verified domain and the user meets the Enterprise User criteria.

Definitions

• Account holder: The person who uses the account day-to-day. The individual themselves may or may not be the account owner.
• Enterprise owner: One or more people who represent the business entity who purchased a paid plan with GitLab, hold Owner permissions in that paid namespace, and are claimed as an Enterprise User.

Note: For the purposes of support, a user may still be considered an enterprise user when they meet support’s definition for an enterprise user.

Conditions for GitLab.com users

A GitLab.com user must meet one of the following conditions to be eligible for a 2FA reset.

1. The user occupies a seat in a paid group on GitLab.com, or a top-level group owner intends to add the user to the paid group.
2. The user is claimed as an Enterprise User.
3. The user meets the support definition for an Enterprise User.
4. The user is the primary billing contact on a current invoice for a GitLab.com purchase.
5. A GitLab team member (account managers, CSMs, or others) collaborates with the holder of this account in an account management project.
6. The user account is required for SSO access to Customers Portal to manage a paid subscription - see: Conditions for 2FA Reset when account is used to access Customers Portal.

More succinctly: they’re paid, they use the account to pay, or we use the account to communicate with them.

In many cases, a top-level group owner may submit a ticket on behalf of the user. See the Account verification matrix for more information and eligibility.

Account verification matrix

Find the Account verification matrix on the Account Owner Verification handbook page.

Conditions when account is used to access Customers Portal

Customers Portal requires all customers to access through a Linked GitLab Account.

The user is eligible and 2FA can be reset when one of following conditions are met:

1. The request is made by the primary billing contact on the latest invoice for a GitLab subscription.
2. The GitLab account is linked to the customers portal account for the primary billing contact on the latest invoice for a subscription purchase.

If an invoice can not be provided, suggest sign in with legacy email/password, where an invoice can be downloaded.

Keep the Ticket simple and accurate

Because 2FA removal tickets are a matter of record, the ticket must be simple, accurate, and tightly focused on the access issue. Do not allow the customer to bring up unrelated topics.

Disable 2FA with support intervention

Support intervention for 2FA removal after the above steps have been attempted is only possible for users with an existing paid plan when the ticket is created. For security purposes, Support will not process 2FA resets for users who are added to a paid subscription for the express purpose of having 2FA disabled on their account.

Workflows

Request for 2FA removal initiated by the account holder

Requests initiated by the account holder will be prompted by an autoreply to provide information to satisfy the security challenges.

Step 0: Validation

Some initial validation steps will occur automatically:

• Email / Username match
• Group membership validation
• Group subscription validation

If any of these are inaccurate, the ticket will be closed.

If a user submits a 2FA reset request ticket using the 2FA Assistance category but does not use the 2FA removal ticket subcategory, set the form subcategory to 2FA removal. If the ticket is obviously about 2FA reset but the customer didn’t use any of the 2FA ticket categories, use the General::Forms::Incorrect form used macro to have Support Operations take the appropriate action on the ticket. If the user is not eligible for support, the ticket will automatically close.

Step 1: Checking challenge answers

Note: In case the user sends back very minimal information and it’s clear it’s not sufficient or the answers are vague, reply asking for more information immediately after their response. You can provide some additional guidance, such as “please provide the exact date and time of the commit, not just an approximate one”.

1. To verify the challenge answers use the Zendesk GitLab User Lookup App or, for those who have admin access, check at https://gitlab.com/admin/users/USERNAME.

2. Use the ZenDesk GitLab Super App’s 2FA Helper to determine the risk factor (GitLab internal) based on the user’s answers. Data classification criteria and any notes are in the Internal Handbook - Data Classification table (GitLab internal), which is considered the source of truth. If you need to leave a comment manually (instead of through the app), use the Support::SaaS::Gitlab.com::2FA::2FA Internal Note macro to put an internal note on the ticket.

   • Challenge answers must be evaluated against a paid namespace if the user is a member of any paid namespace. If the user is not a member of a paid namespace, refer to Conditions for 2FA Reset Consideration for further guidance.

3. If verification passed: Request that your decision be peer-reviewed by another member of the team via Slack #support_gitlab-com. They will perform the steps in 2a.

4. If the verification failed: Move to step 2b.

Step 2a: User successfully proves account ownership

This section is typically done by the peer reviewer. If needed, the peer reviewer (or approving manager) may leave an approval note, in which case the original reviewer will perform the actions.

1. If you agree with the decision, sign into your admin account and locate the username in the users table or by going to https://gitlab.com/admin/users/usernamegoeshere
   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 Support::SaaS::Gitlab.com::2FA::2FA Removal Verification - Successful macro.

Step 2b: User fails to prove account ownership

Note: Do not provide hints to answers, or let the user know which challenges they got right or wrong. That is how social engineering works!

1. If the user is unable to pass the risk factor:
   1. Inform them that without verification we will not be able to remove 2FA, but they may request an Enterprise Owner create a request on their behalf (if they would qualify), use the Support::SaaS::Gitlab.com::2FA::2FA Removal Verification - GitLab.com - Failed - Final Response macro.
   2. Mark the ticket as “Solved”.

Request for 2FA removal initiated by an Enterprise owner

Requests initiated by an Enterprise owner should include a Support PIN.

Note that Zendesk performs the following checks when a ticket is submitted for 2FA removal initiated by an Enterprise owner:

1. Has support entitlement?
2. Requester email domain matches target email domain?
3. Requester is owner of top-level paid namespace?
4. Target is a member under the top-level paid namespace?

If any of those fail, then the user is sent the regular 2FA challenges. Use step 1b below in this case.

If other challenges are sent, note that owners should answer the challenges in reference to their own account. Other answers are not acceptable.

Step 0: Validation

Some initial validation steps will occur automatically:

• Email / Username match
• Group membership validation
• Group subscription validation

If any of these are inaccurate, the ticket will be closed.

Step 1a: Verifying Support PIN

Note: In case the user sends back very minimal information and it’s clear it’s not sufficient or the answers are vague, reply asking for more information immediately after their response.

1. If the user was sent regular challenge answers, use step 1b instead.

2. Use the ZenDesk GitLab Super App’s 2FA Helper (as of May 1, 2025) to determine the risk factor (GitLab internal) based on the user’s answers. Data classification criteria and any notes are in the Internal Handbook - Data Classification table (GitLab internal), which is considered the source of truth. If you need to leave a comment manually (instead of through the app), use the Support::SaaS::Gitlab.com::2FA::2FA Internal Note macro to put an internal note on the ticket.

3. To verify the Support PIN use admin access and check at https://gitlab.com/admin/users/USERNAME.

   • Note: Ensure the Support Pin was provided from the respective owner on the ticket. We cannot accept the Support Pin if it was provided by another user on the ticket on behalf of an owner.

4. Since the user was sent the Support PIN response, the other required conditions are already matched:

   • Requester is an Enterprise owner
   • Target is an Enterprise user

5. If verification passed: Request that your decision be peer-reviewed by another member of the team via Slack #support_gitlab-com. They will perform the steps in 2a.

6. If the verification failed: Move to step 2b.

Step 1b: Checking challenge answers

Note: In case the user sends back very minimal information and it’s clear it’s not sufficient or the answers are vague, reply asking for more information immediately after their response.

1. Skip this step if the user was sent the Support PIN autoresponse in Zendesk.

2. To verify the challenge answers use the Zendesk GitLab User Lookup App or, for those who have admin access, check at https://gitlab.com/admin/users/USERNAME.

3. Use the ZenDesk GitLab Super App’s 2FA Helper to determine the risk factor (GitLab internal) based on the user’s answers. Data classification criteria and any notes are in the Internal Handbook - Data Classification table (GitLab internal), which is considered the source of truth. If you need to leave a comment manually (instead of through the app), use the Support::SaaS::Gitlab.com::2FA::2FA Internal Note macro to put an internal note on the ticket.

   • Challenge answers must be evaluated against a paid namespace if the user is a member of any paid namespace. If the user is not a member of a paid namespace, refer to Conditions for 2FA Reset Consideration for further guidance.

4. If verification passed: Request that your decision be peer-reviewed by another member of the team via Slack #support_gitlab-com. They will perform the steps in 2a

5. If the verification failed: Move to step 2b

Step 2a: Enterprise Owner successfully proves their identity

This section is typically done by the peer reviewer. If needed, the peer reviewer (or approving manager) may leave an approval note, in which case the original reviewer will perform the actions.

1. If you agree with the decision, sign into your admin account and locate the username in the users table or by going to https://gitlab.com/admin/users/usernamegoeshere
   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 Support::SaaS::Gitlab.com::2FA::2FA Removal Verification - Successful macro.

Step 2b: Enterprise Owner fails to prove their identity

Note: Do not provide hints to answers, or let the user know which challenges they got right or wrong. That is how social engineering works!

1. If the user is unable to pass the risk factor:
   1. Send the additional challenges with the Support::SaaS::GitLab.com::2FA::Additional 2FA Challenges macro.
   2. You can ask the owner to generate a Support PIN and provide it to us in a response to the ticket, as an owner vouch. NOTE: If another user is CC’d on the ticket, once you’ve verified the Support PIN ask the user to generate a new PIN to revoke the previous one.
      • Note: Ensure the Support Pin was provided from the respective owner on the ticket. We cannot accept the Support Pin if it was provided by another user on the ticket on behalf of an owner.
   3. You may also leverage Backup methods for authenticating an owner.
2. If the user is still unable to pass the risk factor:
   1. Inform them that without verification we will not be able to remove 2FA, use the Support::SaaS::Gitlab.com::2FA::2FA Removal Verification - GitLab.com - Failed - Final Response macro.
   2. Mark the ticket as “Solved”.

Backup methods for authenticating an owner

If a group owner does not include the owner vouch, you may use another method to verify their identity. It must be an action that has been specifically instructed by Support and identifiably unique to the situation. Some examples include having the owner:

• create a private snippet, containing the ticket number as a string.
• create an issue in a project they have access to with a specific piece of text that you provide.
• create a new project at a path that you provide.

Large Customers (Deprecated)

Flowchart

Below is a flowchart that can help you to visualize the steps described in the 2FA removal within GitLab section above.

flowchart TD
    A[Customer opens ticket]
    B{Is user a support contact?}
    C[Autoresponse is sent]
    D{🟡 Use Incorrect Form Macro}
    E[🛑 Ticket is closed]
    F[Follow Account Holder workflow]
    G[Follow Enterprise Owner workflow]
    H([Score challenges using Acct Verify App])
    I{Challenges passed?}
    J[Peer Review]
    K{Peer Review passed?}
    L{Check Appropriate workflow}
    M[Account Holder workflow]
    N[Enterprise Owner workflow]
    O[🛑 Close ticket]
    P([🟡 Send additional challenges - if none exist, 🛑 close ticket])
    Q((🟢 Peer reviewer disables 2FA, </br> sends response, solves ticket))
    A ---> B
    B ---> |Yes| C
    B ---> |No| D
    D ---> |Associated?| C
    D ---> | Not associated? | E
    C ---> |Request initiated by the account holder| F
    C ---> |Request initiated by an Enterprise owner| G
    F ---> H
    G ---> H
    H ---> I
    I ---> |Yes| J
    I ---> |No| L
    J ---> K
    K ---> |Yes| Q
    K ---> |No| P
    L ---> M
    L ---> N
    M ---> O
    N ---> P
    P ---> I

click D href "#step-0-validation"
click F href "#request-for-2fa-removal-initiated-by-the-account-holder"
click G href "#request-for-2fa-removal-initiated-by-an-enterprise-owner"