Single Sign-On (SSO) Configuration

Our Single sign-on (SSO) implementation is very flexible, as we do not require that the Identity Provider (IdP) server be able to directly communicate with the Shotgun server or vice versa. The flow of information which goes from one to the other is signed and transits via the client application. Usually this will be the browser that connects to Shotgun.

The IdP configuration must be done first. The IdP must send to Shotgun the login_id, which maps to the Shotgun login of the user. This is the key link between the two systems. In the context of an existing Shotgun site transitioning to SSO, please ensure that what is sent by the IdP matches the existing login in Shotgun. Failure to properly align the login_id sent by the IdP and the Shotgun login may result in duplicated users.

When transitioning an existing site, the first step is to audit the login used in Shotgun. If it is not possible, or too complicated, to align the two sets of logins, Shotgun offers a way to deal with this issue for existing users. Learn more in the Shotgun Administrator section.

We have split the configuration guide in two sections: for the IdP and for the Shotgun administrator.

IdP Administrators

Shotgun uses SAML 2.0 to implement SSO support. It is a standard that has been used for a number of years and it is supported by most of the IdP providers we have considered.

Every IdP system has a different mechanism to manage them. We will offer example integrations in ADFS and Okta, but things may differ in your environment.

The SAML Attributes

In your IdP configuration, you will need to add attributes to be passed on to Shotgun.

The SAML2 response payload must contain the following attributes:

Name Type Presence Notes
login_id string Mandatory The login ID the user will have in Shotgun.
This must be unique within Shotgun, and consistent from session to session.
firstname string Mandatory The user’s first name.
lastname string Mandatory The user’s last name.
email string Mandatory The user’s email address.
access string Mandatory Can only have a value of true or false.
If true, the user will have access to Shotgun.
groups string Optional If not present, or empty, the user’s permission group will not be modified from its current value. For a new user, the default user permission group will be used, as defined in the Site Preferences.
If it is present, it should correspond to the name of one of the permission groups defined in Shotgun. If the name does not match, the user will be granted the default user permission group.
ex: “Admin”

Notes

  • The groups attribute is optional, and if absent (or invalid) will not modify the user’s permission group. Given the added complexity of populating this attribute, we strongly suggest to leaving it out, at least initially, to facilitate the initial configuration. This can be managed by the Shotgun Administrator.
  • We do not use the NameID provided in the SAML payload. Instead we rely on the client-provided attribute login_id.

There are a number of strategies that can be used to decide on the login_id, access, and groups.

The login_id must be unique and constant. Email addresses or names may seem like good candidates, but it is important to understand what needs to be done should they ever change (e.g., someone changes their last name).

For access and groups, one common strategy in a Windows environment is to use Active Directory Security Groups. The presence of a user in a given group is reflected in the attribute value.

We strongly suggest to leaving out the groups attribute when first configuring the IdP. Then you can decide later if it is desirable to manage this centrally or if it can be left to Shotgun Administrators.

The SAML Endpoints

The Shotgun server defines two SAML specific endpoints. These will be active only if SAML is set as the Authentication method, or when testing your SAML configuration.

The following endpoints will be necessary when you configure your IdP for Shotgun.

URL Notes
https://YOUR_SITE_URL/saml/metadata The SP endpoint where Shotgun publicizes its other endpoints.
https://YOUR_SITE_URL/saml/saml_login_response The endpoint where the IdP must send its encrypted claims to Shotgun.

Identity Provider (IdP) Configuration

The next step is to configure your identity provider. While we can't provide guides for every possible provider, here are convenient step-through instructions for 2 of the most popular:

The next steps

Now that you have configured your IdP, your Shotgun Administrator is ready to configure and test Shotgun with the required information.

Your Shotgun Administrator will need:

  • the SAML 2.0 Endpoint (HTTPS) URL,
  • The Public Certificate used by the IdP to sign its payloads, and
  • The Identity Provider Issuer string.

The actual name used for these may change depending on the IdP being used.

Ideally, you will want to be available during the Shotgun configuration to help with troubleshooting and fixing any issues.

Shotgun Administrators

Before attempting to configure Shotgun, you need to wait until the IdP is configured. Once that is done your IdP Administrator will provide you with the information needed by Shotgun.

Configuring Shotgun

After logging in as an Administrator, you need to go to the Site Preferences page, via your settings menu in the top right corner:

Shotgun User Menu
Shotgun User Menu

Proceed to the Authentication pane and open it up:

Shotgun authentication pane
Shotgun Authentication Pane

Warning: Do not enable SAML Authentication before you have tested it.

If you do not see the ’SAML Authentication’ radio button and section, please contact Shotgun Support so that it can be enabled.

You can now enter the information by opening up the SAML Authentication section:

Shotgun Authentication Pane Settings
Shotgun Authentication Pane Settings

  • SAML 2.0 Endpoint (HTTPS): The URL on the SSO backend where Shotgun will redirect for the Authentication.
  • Public Certificate: The certificate required to communicate with the IdP.
  • Identity Provider Issuer: The entity ID for the service, as defined by the IdP.
  • SSO Configuration (YAML Format): Additional configuration settings. See the next section.

Do you need to use additional configuration ?

The SSO Configuration panel allows for additional configuration, following the YAML format. These options are used only in special cases.

The following is the list of accepted tokens and sample uses. Unknown tokens will simply be disregarded. Improper formatting or erroneous values may affect the whole set of configuration. Please be careful.

Encryption

By default, we only use encryption with the IdP provided public key. If needed, Shotgun can also sign its requests. Once the certificate is generated, the public certificate will need to be made available to the IdP. The private key will be entered here:

service_provider:
  private_key: "KEY" # the key used for encryption
security:
embed_sign: true # embed the signature in the SAML header authn_requests_signed: true # authorization requests are encrypted logout_requests_signed: true # logout requests are encrypted logout_responses_signed: true # logout responses are encrypted

Single Log Out (SLO)

By default, we do not make use of SLO. Should you need it, it can be configured with the following token:

identity_provider:
  slo_target_url: https://single.logout.url

Ignore some fields in update

As mentioned before, Shotgun considers the IdP as the authoritative source for user information. Any information in Shotgun will be updated from the IdP at login and when the claims are renewed.

In some particular circumstances, it may be necessary to protect the information set in Shotgun by an Administrator and prevent it from being updated with the IdP information.

The list of allowed tokens are: firstname, lastname, email, and groups.

ignore_updates:
  - email

Auto-provisioning

Default: true

When auto-provisioning is enabled, any user who is granted access to Shotgun but does not exist in its database will automatically be created with the information given by the IdP. If no group is given, the user will be assigned Shotgun’s Default User Permission Group value, as indicated by the Site Preferences’ Advanced settings.

Automatic user creation is often not desirable. The new user will not have access to the relevant projects and will require the intervention of a Shotgun Administrator to fix. It is usually better for the Administrator to create the users in advance, with the proper permissions and the correct login. This will make the user’s experience easier.

autoprovision: false

Skip sending email upon SSO activation

Default: false

Whenever SSO is activated or deactivated, an email is sent to all of the active users. This email lets them know about the state of SSO and any action they need to take.

We strongly recommend that you disable the activation emails when doing the initial tests on your Staging server or when doing tests on your Production server. This avoids confusion for your users and unnecessary support calls.

skip_activation_email: true

Use a secondary browser window to renew the user credentials

Default: false

Shotgun on the web browser uses an iframe to renew the user’s claims against the IdP server. Some IdP systems do not allow clients to use an iframe for authentication. For example, Okta’s default configuration denies the use of iframes unless explicitly changed by an IdP Administrator. In the case of Okta, this is a system-wide setting that will affect all other applications, not just Shotgun. Your IdP may have similar limitations or restrictions.

To get around this constraint, Shotgun will open a secondary browser window in the bottom left corner of the screen. It asks the user not to close this window. Shotgun should be configured with this setting if iframes are not allowed.

saml_claims_renew_iframe_embedding_disabled: true

Testing your configuration

Once you have entered the required values, save your settings but do not set the authentication mode to SAML Authentication yet. Use the Test link to validate your configuration first. You will likely need to allow Shotgun to open pop-up windows.

We strongly suggest that your IdP Administrator be present when doing your tests. This can help when troubleshooting.

Failure

Shotgun Test Failed
Shotgun Test Failed

When this occurs there should be some indication, pop-up, or output to help you identify the problem. If you and your IdP Administrator cannot locate the issue, you may need to open a Shotgun Support ticket so that we can have a look at the server logs.

Success

Shotgun Test Success
Shotgun Test Success

If the test is successful you can proceed to the next steps.

The next steps

Now that the configuration is working, you are ready to proceed.

Test on your Staging server first

This has been mentioned a few times before, but we really must stress the need for this step. It helps ensure that all of your tools, scripts, and third party applications are communicating correctly with Shotgun. You must confirm that all the pieces of your production pipeline are working as expected. Once SSO is enabled on your Production site, stability is the main concern.

Before SSO can be enabled on your production site, we need a clear and precise statement from you indicating that all of your tests in Staging were successful. This also lets our Support team keep a look out for SSO related issues on your site.

Enabling SSO

On your Staging site, the email notification should be disabled to prevent confusion for your users. You will likely be cycling a few times, enabling and disabling SSO.

On your Production site, you might also want to temporarily disable email notifications if you plan on doing tests. Enabling SSO will terminate all ongoing sessions on the site, except for the user changing the configuration. This should be done during an off-peak period, when few users are interacting with Shotgun.

While an email will be sent to all the active users once SSO is enabled, you may also elect to send out a notification email prior to that. This email can explain to the users why and when this is being done, and who they should contact if they run into any issues.

The Shotgun login flow will try to fix initial login issues, if possible. Users will have the option of linking their existing accounts based on emails or authenticating themselves with their old username and password. While this may provide a way to overcome an initial connection, it is also complex and error prone. It is possible that duplicate users will be created erroneously, resulting in support calls and being charged for those duplicate users.

The goal is to make the transition to SSO transparent to your users. To that effect, there are a few steps that can be taken to make the transition seamless.

Easy transition for existing users

The core of the authentication process revolves around the match between the login_id provided by the IdP and the existing Shotgun login. An audit of the existing Shotgun user base should be done to validate that there is a constant rule used to assign login values, and to ensure that the IdP will be in a position to send a matching login_id.

When there is a match, users will connect with their Shotgun site immediately, without any additional steps or input on their part. This is the ideal situation.

As a Shotgun Administrator, you can take steps to resolve cases where Shotgun login naming is inconsistent or when it is not possible to easily ensure that the IdP sends out the correct login_id.

First solution:
Simply change the user’s Shotgun login to match the IdP login_id. You will need to let the user know what the new username is. Should SSO be turned off, they will need the new username to connect to Shotgun, using their old password.

Second solution:
Link the IdP account with the Shotgun account:

  1. Connect to your Shotgun Site using an Administrator account.
  2. Navigate to the People page:
     
    Shotgun user menu

  3. Ensure that the column Single Sign-On Login is visible:
     
    Shotgun People before fix

  4. Edit the field for the problematic user and enter the login_id send out by the IdP.
     
    Shotgun People after fix

  5. Now the accounts are linked and the problematic user will be able to log in as the proper user.

You may have to follow these steps for a number of irregular Shotgun logins.

Inviting and creating new users

There are two ways to add new users when SSO is enabled. In both cases, it is mandatory that the IdP be updated to allow access to these users prior to taking any actions in Shotgun.

  1. Connect to your Shotgun Site using an administrator account.
  2. Navigate to the People page:
     
    Shotgun People Add

  3. Depending on the situation, you have two options:
  • The first option is to invite a new user. This is the default option. Clicking on the + Person button will bring up the Invite dialog:
     
    Shotgun people invite
    This dialog will send out an invitation email to the user. No changes are made within Shotgun. The user must already have been granted access to Shotgun in the IdP.
     
    If autoprovision is set to false, the user will not be able to use Shotgun until a user is created by an Administrator.
     
    Otherwise, on first login the user will be presented with a dialog asking them if they want to link with a previous existing account or create a new user.
     
    The former choice will lead them to a page where they need to authenticate using the Shotgun username and Shotgun password of the previous account. The latter choice will create a new user which does not have access to any project.
     
    Note: Sending an invite may not be the ideal choice to add a new user.
     
  • The second option is to create a new person. Click on Create a new Person now to bring up the old user creation dialog:
     
    Shotgun people create
    This will effectively create a new user in Shotgun, with the specified access, and also send out an invitation email to the specified address. Be careful with the information entered, as it may be updated by the IdP claims when the user initially logs in (unless prevented by the Ignore some fields in update option).
     
    You may find it useful to modify the dialog by clicking on more fields and adding the Single Sign-On Login field. This allows you to enter the additional information to ensure a seamless connection by the new users.
     
    Note: This is the preferred method for adding users.

Login flow in Shotgun when SSO is enabled

When SSO is enabled, Shotgun has to make additional checks before the user can connect. This is even more the case on the first connection. Here is the logic behind the login flow:

Login Flow
Login Flow

Two important situations that may occur are account linking and user creation. In either situation, the user will need to proceed through a set of steps, which may be complicated for them.

To make their experience as seamless as possible, the Shotgun Administrator should be the one creating the users and/or linking the accounts. This requires more work on the Administrator’s part, but it is beneficial to the users. See Easy transition for existing users for more information.

Accessing your Shotgun site with internal tools and third-party applications

Any internal tools or scripts that use a username / password pair to initiate a connection with your Shotgun server will need to be modified.

Some of the options available:

  • Use the Authentication module offered with the Shotgun Toolkit (will require PySide/PyQt).
  • Use Shotgun Desktop to handle authentication and obtain the session token from it.
  • Implement your own SSO Login flow to your IdP. We can provide the high-level steps required, as well as additional technical information.

For third-party applications, you will need to contact the individual developers if SSO in Shotgun is not supported.

Wrapping up

For existing users, ideally the login_id should match the Shotgun login. But that may not always be possible.

How to choose the login_id to be sent by my IdP

Remember the constraint that the login_id be both constant over time and unique.

Some of our clients have decided to use emails, or firstname.lastname as the login_id. This may be problematic if the user name changes. However, name changes may not happen very often, which makes this a viable choice, and will only require occasional intervention by a Shotgun Administrator.

Other clients have used their employee’s ID. While this may be resistant to changes in employee name, it is a bit delicate for Shotgun Administrators to handle these. It is not obvious which employee the ID maps to, and can lead to input errors.

Additional information

Should you encounter any serious issues during the configuration process, please contact our Support team.

After the initial onboarding meeting, we are also available to help during the initial configuration or for troubleshooting.

Any suggestions or comments you have on this guide will be appreciated. If you use IdP that we have not documented, we would like to improve this guide by adding the set up instructions you followed, as well as screenshots.

To learn more, please see “SSO in Shotgun: An Administrator’s guide” and “Single Sign-On troubleshooting.”

Follow

0 Comments

Please sign in to leave a comment.