The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing


External Resources

More Info

Page tree
Skip to end of metadata
Go to start of metadata

Sauce Labs supports Identity Provider (Idp)-initiated Single Sign-On (SSO). This feature allows customers' authorized employees access into Sauce Labs in a moderated fashion, as an alternative to using credentials. SSO is available to invoiced accounts, and can only be implemented by the organization admin of the account. If you are an invoice customer, the following sections will guide you on how to set it up.  

See the following sections for more information:

What You'll Need


  • You need to have an enterprise license for Sauce Labs

  • You need to be an organization admin for your account
  • You need to export the SAML metadata file for your identity provider; see below for details
  • You need to be able to use IdP-initiated SAML for this feature

SAML2.0 Metadata File

Before you can set up SSO, you'll need to export the SAML metadata file for your identity provider and upload it to Sauce Labs when you're configuring SSO (Account > Team Management > View Settings > Single Sign-On).

The SAML metadata file is an XML file that is generated by your IdP and contains information required to establish the link between it and Sauce Labs SSO. The Admin for your IdP should be able to provide this file for you. The EntityID attribute must be included in your XML file, set to the Issuer URL (e.g.,, for the integration to work correctly.

SAML2.0 SAML Response Payload

The following attributes must be included in your SAML assertion, with the expected values, for the integration to work correctly.


Expected Value


IssuerURL identifying your organization
NameIDUser's email

NameID Specification

By default, many IdPs don't set the NameID attribute to be the email address of the user. If the value for this attribute is something other than an email address, you can still integrate your IdP with Sauce SSO.

We recommend setting it to the email address, as this makes it easier to manage through the IdP. When the SSO username is created, only the section preceding the @ is used. For example, from the email, only john.smith would be used.

If the saml:NameID field contains only a user name and no @ symbol, then the SSO username will be based on your Domain Name. If your domain was sauce and the field value was john.smith, the SSO username would be sso-sauce-john.smith.


This is a required attribute within the SAML assertion that indicates the specific users the assertion is intended for. It must be equal to the value of entityID from SauceLabs metadata based on your data center. For details, see the Single Sign-On Configuration section in Data Center Endpoints.

Configuration Information for SSO

The Signing/Encryption Certificate and Entity AssertionConsumeURLs required for configuring Sauce Labs SSO vary based on your data center. For details, see Data Center Endpoints. Here are some things to be aware of:

  • The Assertion/Issuer Name is Sauce Labs
  • Sauce Labs does not provide a staging environment for pre-integration testing of SSO
  • Single log-out is not supported, but all sessions time out after 30 minutes of inactivity

Setting Up SSO

When you set up SSO with Sauce Labs, you are establishing a connection between the IdP used by your organization, such as Okta or Microsoft's Active Directory, and your Sauce Labs account, that will enable users to log in with their IdP credentials to access Sauce Labs.

  1. In the Account drop-down menu, click Team Management
  2. In the Organization Settings panel, click View Settings
  3. On the Organization Settings page, click the Single Sign-On tab. 
  4. Enter a Unique Identifier String.
    This string will be applied to user names to make sure that your users will have unique names associated with your account. 
  5. Upload the SAML Metadata File provided by your IdP that contains the list of your SSO users.
    Sauce Labs SSO supports most SAML2.0 metadata files. For more information about specific IdPs, check out these topics:
    Configuring Active Directory Federated Service for Sauce Labs SSO 
    Configuring Okta for Sauce Labs SSO 
  6. Under Enable Single Sign On, toggle the switch to Enabled

NOTE: If the account you're setting up with SSO is not the only account your organization has with Sauce, the EntityID field must be unique for each account, otherwise the setup will fail. The EntityID field is a simple string that can be changed manually in the metadata file prior to upload. If users are added to your IdP after you've set up SSO with Sauce Labs, then Sauce Labs accounts will be created for them the first time they attempt to log in using their SSO credentials. 

Advanced Setup Options

Advanced setup options include:

Default Team PlacementAssign SSO users to a default team when they are added to Sauce Labs.
Require Single Sign-OnEnabling this option will require users to log in to Sauce Labs using their SSO credentials, even if they already have individual Sauce Labs accounts. These users can run test automation using credentials.

Adding Non-SSO users to Sauce Labs

To add users to your Sauce Labs account who are not included with your SSO users:

  1. Log in to Sauce Labs as the account owner.
  2. In the Account menu, select Team Management.
  3. Select the Users tab, and click Add User.
    1. If SSO and Require Single Sign-On are enabled, you are adding a user outside your Idp, which means they will not be able to log into Sauce portal using the credentials you are creating, only run test automation. Use "Add user manually".
    2. If SSO is enabled but Require Single Sign-On is not, you can either add the user manually or use "invite via email."
  4. Enter the user information, and click Add User.

Here are a couple example scenarios in which you may need to add non-SSO users to your Sauce Labs account:

  • You have a user account for Jenkins or another CI/CD server that needs to access Sauce Labs, but won't log in via the UI. This option is consistent with the Require Single Sign-On option, as that machine or user will never log into the SauceLabs portal. 
  • You have a group of contractors who will be using your Sauce Labs account, but won't be added to your organization's IdP. This option is NOT consistent with the Require Single Sign-On option, as in this case the contractors are likely to need access to the Sauce Labs portal.

Additional Resources