Administering two-factor authentication for a site

While two-factor authentication brings more security to the table, it also increases the possibility that a user might accidentally be locked out of Shotgun. In order to keep the good guys up and running in the system, an Admin may need to help out from time to time. This document provides some technical details that will be important to Admins.


Two-factor authentication is currently a site-wide preference in Shotgun. If enabled, all accounts on the site will be required to use the additional security measure when logging in. Admins are able to control two-factor authentication themselves in the Site Preferences.

When two-factor authentication is initially enabled for a site, any user with an existing Shotgun session will be logged out automatically (similar to what happens if your Shotgun site gets a new release update when a user has an existing session). This is to ensure that all users immediately set up the additional security measure that the feature brings. We recommend clear communication with your team before turning two-factor authentication so there are no surprises.

The next time users log in to the Shotgun site, they will be guided through the two-factor authentication set up process, which will be required from that point on. Also, any new users created in Shotgun will have to set up two-factor authentication before they can access the site.

Helping locked-out users

In the unfortunate event that a user can’t access Shotgun because of a two-factor authentication or login issue, you can reset the account to hopefully unblock him/her.

Get help

Users having two-factor authentication issues can request help through Shotgun via the Get help button on the code entry screen:

This will send an email to you and anyone else set to receive security emails for the site. These emails are driven by the Subscribe to all Security emails field on the People entity, consistent with all of the other email subscription settings. By default, anyone in the Admin permission group should have these emails on, and people can opt in or out of them based on their studio’s workflow (and Shotgun field permissions).


Reset credentials

When a user is locked out, an Admin will typically need to reset his/her credentials, since the user can’t get in to update his/her own account settings anymore. Resetting a user’s two-factor authentication credentials is just like resetting a user’s password (if you’re familiar with Shotgun’s existing mechanism for this):

  1. Locate the user’s record in Shotgun.
  2. Display the Password field if it isn’t already.
  3. Click Reset Credentials.
  4. Make sure the Reset Two-Factor Authentication checkbox is checked.
  5. Click Save.

This will send an email to the user with a link that guides him/her through the process of setting up two-factor authentication again. Note that the user’s password will remain the same unless the Reset Password checkbox was checked in step 4. Resetting two-factor authentication does not necessarily require the password to also be reset.

Note: Admins can generate backup codes on behalf of a user to help with these situations.

Users without backup codes

We recommend that users keep a set of backup codes, since you never know when you might need them. We also recommend that Admins in turn pass this recommendation along to their site’s users. That said, sometimes a user can be locked out and not have backup codes. There are three main device-related scenarios to navigate:

  1. The user’s phone is lost or stolen.
  2. The user doesn’t have his/her phone, but it’s not lost/stolen.
  3. The user got a new phone but didn’t pair it to his/her Shotgun account.

Each of these scenarios is covered in our two-factor authentication FAQ. For the first and third scenarios, the user will need to have some device available in order for the resetting of the user’s two-factor authentication credentials to unblock him/her. So for the first case, hopefully the User has replaced the lost/stolen phone. With the third case, there is at least the new device to rely on so a reset will address the need. For the second case, Admins can generate backup codes on behalf of the user.