Set up single sign-on (with SAML 2.0)
Integrate your SAML 2.0 identity provider (IDP) with Polaris to use single sign-on (SSO) and manage access to Polaris from your IDP.
Overview
Security Assertion Markup Language (SAML) is a single sign-on (SSO) standard for messages between service providers (like Polaris) and IDPs (like Okta) to support user authentication. After you enable single sign-on in Polaris:
- You can manage access to Polaris using your IDP.
- Your users don't have to maintain a separate password for Polaris. Instead, users sign in using credentials managed by your IDP.
Polaris does not automatically retrieve user or group information from your IDP when you enable single sign-on. Instead, Polaris only retrieves a user's information from your IDP (which may include groups they belong to that have access to Polaris) when they sign into Polaris using single sign-on successfully.
None of the actions you perform in Polaris can modify a user or group's settings in your IDP.
Manage Polaris groups through your identity provider
- Adding groups to Polaris that aren't already synchronized.
- Adding the user to (or removing the user from) groups that are already synchronized with Polaris.
Group names in Polaris must be unique, and only use lowercase characters. If a group's name includes uppercase characters in your IDP (GroupName), the group's name will only use lowercase characters in Polaris (groupname). When you synchronize groups in your IDP with Polaris, you need to specify what Polaris will do when the name of a local group matches the name of a group in your IDP. Polaris can either merge groups with matching names, or automatically rename local groups to preserve them.
If you choose to merge groups, the group's permissions do not change. The group's membership is overwritten to match membership in your IDP. For example:
Groups before merge | Groups after merge |
---|---|
Polaris Developers (IDP group)
|
Polaris Developers (IDP group)
|
polaris developers (local group)
|
polaris developers (synchronized group)
|
If you choose to rename local groups, Polaris appends a number to the end of the local group's name (for example, polaris developers becomes polaris developers-1). The local group's permissions and membership do not change. Then, Polaris creates a new group with the original name (polaris developers). The new group's membership matches membership in your IDP, and no permissions are mapped to the new group. For example:
Groups before rename | Groups after rename |
---|---|
Polaris Developers (IDP group)
|
Polaris Developers (IDP group)
|
polaris developers (local group)
|
polaris developers-1 (local group, renamed).
|
polaris developers (synchronized group)
|
Disable automatic user provisioning
Disable local authentication
Prerequisites
Setting up single sign-on requires the following:
- Organization Administrator permissions in Polaris. Only Organization Administrators can generate SAML metadata and configure single sign-on in Polaris.
- An IDP that supports SAML 2.0.
- Sufficient permissions to create an integration with Polaris in your IDP.
Generate SAML metadata in Polaris
Add SAML metadata from Polaris to your IDP
Use values in the sso_saml_metadata.xml
file to set up mappings in your IDP. The steps to complete this vary from IDP to IDP.
Minimally, you must create claims for three user attributes:
- Email (
user.email
) - First name (
user.firstName
) - Last name (
user.lastName
)
When you complete this step, your IDP generates the SAML metadata you need to complete the setup in Polaris.
Complete the SAML setup in Polaris
Grant users and groups access to Polaris
Update your single sign-on settings
- Go to My Organization > Authentication.
- Select Edit > Next.
- Update your single sign-on settings, as required, and select Done.