Overview

This article explains some key concepts administrators should understand and consider before setting up SAML SSO.

We use Jira for the examples in this article, but the setup is very similar in other Atlassian products.

Understanding SAML SSO

Let's review how SAML SSO actually works at a high level:

  • A user tries to access a protected page in Jira and is required to log in
  • Polar SSO redirects the user to their SAML identity provider (IDP) where the user is asked to log in (unless they already have a valid session)
  • The IDP issues a digitally signed SAML Response message containing the username and other basic user properties
  • Polar SSO verifies that the SAML Response was actually signed by the IDP
  • Polar SSO looks up a Jira account with a username found in the SAML Response

For this to work the SAML response must contains all the information needed by Polar SSO. Jira must also be configured with user directories allowing Polar SSO to locate or create an account for the SAML user. 

User directories and provisioning

An important question to consider is: Can Polar SSO assume that SAML users already have accounts in Jira when logging in, or should accounts be provisioned by Polar SSO?

If both Jira and your IDP are connected to the same user directory (commonly Active Directory), then accounts will already be synchronized and there is no need to provision accounts. This is a common setup when using Active Directory user directories with SAML providers such as Microsoft AD FS (which connects directly to AD), and cloud providers such as Azure AD or Okta (which can synchronize users from AD using connectors).

If this is not the case, you may want to configure Polar SSO to provision and update accounts based on user attributes found in the SAML response message.

Access policies

The Access policy allows administrators to configure which users should log in using which SAML provider. This feature is entirely optional, but is especially useful when you have more than one SAML providers and need to target users to the correct provider.

The SAML providers available for a user may be restricted by:

RestrictionUseful whenExample use case
User DirectoryOnly users in specific user directories should log in AD FS should only be available users in the 'Active Directory' user directory
UsernameOnly users with specific username patterns should to log in Okta should only be available for usernames ending with '@company.com'
Network locationOnly users on a certain network location should log inUsers from a certain office location should log in with AD FS, others using Azure AD

When setting up a provider, Polar SSO will ask some questions to help you configure a sensible access policy during. You can also change this at a later point.

Redirect modes

If all or most users should be logging in with the same SAML provider, then you might want to consider redirecting users directly without asking for usernames. You can even skip the login page entirely. See Redirect modes for more details.

Learn more