Configure SSO

Why use SSO with TestRail?

SSO helps QA teams improve both security and efficiency:

• Security: Prevents password reuse and reduces the risk of stolen or lost credentials.
• Efficiency: Testers log in once and gain access to TestRail and other approved applications.
• Admin control: User accounts are created and managed centrally in your Identity Provider (IdP).

In practice, this means:

• Testers spend less time logging in.
• Admins no longer need to manually add, remove, or update user accounts in TestRail.

Supported SSO protocols

TestRail supports integration with any Identity Provider that uses:

• SAML 2.0
• OAuth 2.0
• OpenID Connect (OIDC)

Prerequisites

Before enabling SSO, make sure you have:

• A TestRail Enterprise license.
• Admin access in TestRail.
• Admin access to your Identity Provider (e.g., Azure, Okta, Google, ADFS).
• Your IdP metadata or configuration details (such as client ID, client secret, redirect URLs).

How to enable SSO in TestRail

1. In TestRail, go to:
   Admin > Site Settings > SSO.
2. Select the authentication protocol you want to use:
   • SAML 2.0
   • OAuth 2.0
   • OpenID Connect
3. Fill in the required settings provided by your IdP.
   • Example: For OAuth 2.0, you’ll need a client ID and secret.
4. Save your changes.
5. Test the connection to confirm your configuration works.

Provider-specific setup guides

Use the following step-by-step guides for your Identity Provider:

• OAuth 2.0
  • Azure | Google | Okta
• OpenID Connect (OIDC)
  • Azure | Google | Okta
• SAML 2.0
  • Azure | Google | Okta | ADFS

User Management with SSO

Once SSO is enabled, you can choose how users authenticate:

• Mixed login: Users can log in with either TestRail credentials or SSO.
• Enforced SSO: Users must log in with the integrated IdP only.

You can also:

• Enable/disable SSO per user: Set this individually or in bulk when editing user accounts.
• Auto-provision users: TestRail can automatically create new users if they successfully authenticate through your IdP.

⚠️ Important: If you deactivate a user in your IdP, you must also deactivate them in TestRail. User statuses are not automatically synchronized.

Next Steps

• If you’re on Professional: Upgrade to Enterprise.
• If you’re already on Enterprise, choose your provider and follow the relevant setup guide.
• Need help? Contact TestRail support.