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. With the rollout of the enterprise_users_automatic_claim feature flag, users are automatically marked as an enterprise user if a group has a verified domain, and the user’s primary email matches a verified domain.

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 have a verified domain.

Conditions for SaaS users

A SaaS 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 an Enterprise User.
3. The user is the primary billing contact on a current invoice for a SaaS purchase.
4. A GitLab team member (account managers, CSMs, or others) collaborates with the holder of this account in an account management project.
5. 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.

Account verification matrix

The table below provides a summary of the available verification options based on the owner and user type:

Requester	Target	Challenges	Notes
Enterprise owner	Own account	Owner passes challenges on own account	If the requestor fails another Enterprise owner may raise a separate request on their behalf. If no other Enterprise owner is available, see internal handbook for other challenges.
Enterprise owner	Member of paid group or intent to be added	Enterprise owner meets base criteria and authenticates request	Multiple enterprise users may be handled per ticket. Target user does not have to be CC’d on ticket.
Enterprise owner	Non-enterprise user	Invalid request type	Account holder must raise their own request and pass challenges
Account holder (Paid)	Own account	User passes challenges on own account
Account holder (Paid)	Other member of same paid group	Invalid request type - must be raised by an Enterprise owner	Communication is direct from the target user who must be CC’d on ticket.
Account holder (Free)	Non-member of group with intent to be added	Invalid request type - request must come from Enterprise owner

To summarize: If a user cannot make use of self-serve methods (lost their account recovery codes and has no SSH key registered) there are two potential ways to validate the request and recover the account: having the account holder open the request, or by having an enterprise owner create the request on their behalf.

See the Enterprise User section on how to identify if a user is an Enterprise User.

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 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. 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 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. As an Enterprise owner, the ticket response generated by the form should also include a Support PIN. If it does not, move to step 2b below.

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

2. 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

3. 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 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 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

For customers who are large enough to have an account management project, a different workflow can be configured for them that will allow Support to more easily disable 2FA for any of their users that require it. Before this process can be used, a GitLab team member from either Customer Success or Sales must perform a few setup steps (described below). If a customer requests this workflow, please refer them to either of those individuals.

Setup (for CS & Sales)

The steps to follow depend on whether or not the customer has a shared Slack channel with us. Either the customer’s Customer Success Manager (CS) or Account Manager (Sales) is responsible for performing this setup. Please proceed to Shared Slack Channel if they do or No Shared Slack Channel if they don’t.

Method 1: Shared Slack Channel

1. Find out which users within the customer’s organization are the ones that will be authorizing GitLab Support to disable 2FA on their users accounts. Obtain both the Slack handle and GitLab username of these users.

2. Create a file called 2FA Verification.md inside of the .gitlab/issue_templates directory of the customer’s Account Management project. If that directory does not exist, create it as well.

3. Populate the 2FA Verification.md file with the template below, taking care to replace the following variables from it with your specific customer’s information:

   • CUSTOMER_SLACK_CHANNEL - The name of the shared Slack channel that the customer’s organization has with us.

   • SLACK_USERNAME - The Slack handle of a user that is authorized to allow GitLab Support to disable 2FA for the customer’s user accounts.

   • GITLAB_USERNAME - The GitLab username of a user that is authorized to allow GitLab Support to disable 2FA for the customer’s user accounts.

     2FA Verification Template

     A user in your organization is requesting to have GitLab two-factor authentication removed from their account. Please review and complete the highlighted sections below.

     Support Engineer Instructions

     • Ping the customer’s organization owners in CUSTOMER_SLACK_CHANNEL using the Notify Customer - Slack template. For this organization the owners are SLACK_USERNAME, SLACK_USERNAME, and SLACK_USERNAME.
     • Fill out the Request Details section below.

     Request Details

     • User Requesting Reset: USERS_GITLAB_USERNAME
     • Support Ticket: TICKET_NUMBER

     Customer Instructions

     • Review the request and get in contact with the user requesting the reset to verify its authenticity.
     • Comment on this issue indicating your approval.
     • Unassign yourself and any others from this issue.
     • Assign to the Support Engineer who opened this issue.

     /assign GITLAB_USERNAME GITLAB_USERNAME GITLAB_USERNAME, /label ~“2FA Reset” ~“Awaiting confirmation”

4. Create a Support Super form submission

   • For “What is this request concerning?”, select Modifications to a Zendesk Global Organization
   • For “What kind of modification are you looking to make?”, select Add 2FA exemption for large customers
   • Fill out the other fields with the correct and relevant information it asks for

Method 2: No Shared Slack Channel

1. Find out which users within the customer’s organization are the ones that will be authorizing GitLab Support to disable 2FA on their users accounts. Obtain the GitLab username of these users.

2. Create a file called 2FA Verification.md inside of the .gitlab/issue_templates directory of the customer’s Account Management project. If that directory does not exist, create it as well.

3. Populate the 2FA Verification.md file with the template below, taking care to replace the following variables from it with your specific customer’s information:

   • GITLAB_USERNAME - The GitLab username of a user that is authorized to allow GitLab Support to disable 2FA for the customer’s user accounts.

     2FA Verification Template

     A user in your organization is requesting to have GitLab two-factor authentication removed from their account. Please review and complete the highlighted sections below.

     Support Engineer Instructions

     • Fill out the Request Details section below.

     Request Details

     • User Requesting Reset: USERS_GITLAB_USERNAME -Support Ticket: TICKET_NUMBER

     Customer Instructions*

     • Review the request and get in contact with the user requesting the reset to verify its authenticity.
     • Comment on this issue indicating your approval.
     • Unassign yourself and any others from this issue.
     • Assign to the Support Engineer who opened this issue.

     /assign GITLAB_USERNAME GITLAB_USERNAME GITLAB_USERNAME, /label ~“2FA Reset” ~“Awaiting confirmation”

4. Create a Support Super form submission

   • For “What is this request concerning?”, select Modifications to a Zendesk Global Organization
   • For “What kind of modification are you looking to make?”, select Add 2FA exemption for large customers
   • Fill out the other fields with the correct and relevant information it asks for

Usage (for GitLab Support)

If a 2FA ticket is opened by an organization that has had this workflow configured for them, perform the following steps to process the request depending on whether or not the customer has a shared Slack channel with us.

Note: 2FA removal for the user is approved by the Customer via the 2FA Verification template. This means the Customer will confirm with the User having 2FA removed and not support.

1. Create Issue

1. Open a new issue in the issue tracker of the customer’s account verification project using the 2FA Verification template and follow all instructions within it. A link to this template should be in the notes for the organization in Zendesk.

2. Contact Through Slack (skip if no shared Slack channel)

1. Within the customer’s shared Slack channel with us, use the template below to alert them to the fact that a new 2FA disable request exists in their account management issue tracker. Be sure to replace the following variables:

   • SLACK_USERNAME - The Slack handle of a user that is authorized to allow GitLab Support to disable 2FA for the customer’s user accounts. If there are more than one, add them as well.

   • ISSUE_LINK - The URL of the 2FA reset issue created on the shared project

     Notify Customer - Slack

     Hi `SLACK_USERNAME` - we've received a request from one of your users to disable 2FA on their account.

     Could you vouch for them by following the steps in this issue: `ISSUE_LINK`?

     Once you've done that, please let me know. If you don't get to this within 24 hours, we'll use our standard account verification procedures to determine if they're eligible for a 2FA reset.

Note: If the customer has created an issue using the 2FA Verification template themselves and sent us a Zendesk ticket with a link to it, skip this step.

3. Wait For Authorization

Wait for the customer to comment on the issue and approve the request to disable 2FA.

As stressed in the Slack notification template, we will wait for the customer’s answer for 24 hours. If no response is received by then, regular 2FA verification will take place via the challenges workflow.

4. Disable 2FA

Once the customer has approved the request, disable 2FA on the user’s account, add an Admin Note on the user’s account, and then close both the support ticket and issue.

Peer review is not required. You may make the change yourself.