Enable SSO

Single Sign-On (SSO) is an authentication method that lets you use the same set of credentials to authenticate to multiple applications. Imply Polaris allows for SSO using identity providers (IdPs) compliant with Security Assertion Markup Language (SAML) 2.0 and OpenID Connect (OIDC) 1.0 protocols. You can configure and broker any IdP compliant with these open standards.

With IdP-initiated SSO, you do not need to create users in Polaris or assign them to groups. User creation and group assignment happens based upon the data from the IdP when a user logs in.

When you configure IdP-initiated SSO to authenticate to Polaris, a button for the IdP automatically appears on the login screen. Users can choose to authenticate with an Imply username and password or with the configured third-party IdP.

The following screenshot shows SSO configured for Okta.

When a user account is managed by an IdP, Polaris displays the IDP tag next to the user email on the Users page. The following screenshot shows the IDP tag displayed next to the emails of IdP-managed users.

Configure SSO

You enable SSO at the organization level.

The AdministerUsers permission is required to configure SSO.

At a high level, the flow to configure SSO using an IdP metadata document is as follows:

• Configure the Polaris application in your IdP.
• Export the IdP metadata document.
• Import the configuration into the Organizational settings console in Polaris.

Configure the Polaris application

Configure the Polaris application in the identity management software you use. Most types allow you to export the IdP metadata file, which you can then import into Polaris. The metadata document includes the issuer's name, expiration, and keys to validate responses from the IdP.

The following example shows a SAML 2.0 metadata file from Okta:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor entityID="http://www.okta.com/<default or custom id>" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
<md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<md:KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>ThisIsNotARealCert</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
<md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://yourcompany.okta.com/app/app_name/your_okta_id/sso/saml"/>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://yourcompany.okta.com/app/app_name/your_okta_id/sso/saml"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>

For instructions on how to obtain the metadata file, refer to the official documentation for your IdP.

Add the identity provider

To add a new IdP, follow these steps:

1. Click the user menu icon located in the top-right corner of the UI.

2. Click Administration.

3. Click Identity providers in the left sidebar.

4. Click Manage identity providers.

5. Click the Add provider drop-down and select from the list of available providers. Polaris displays the configuration page for the IdP you selected.

6. Expand the Import External IDP Config section.

7. Click Select file.

8. Select the metadata file you downloaded.

9. Click Import.

10. Enter information into the mandatory fields marked with an asterisk.

    • Alias: The unique identifier for the IdP. Polaris uses the alias to build redirect URIs for protocols that require a redirect URI or a callback URL to communicate with the IdP. Every IdP must have an alias. Alias examples include facebook, google, and idp.acme.com.

    The following fields are required for the OIDC protocol:

    • Authorization URL: The authorization endpoint that accepts authentication requests. Through this endpoint, you can interact with the resource owner and obtain an authorization grant.
    • Token URL: The token endpoint required to obtain an access token.
    • Environment Authentication: The environment authentication method. In the case of JWT signed with a private key, Polaris uses the organization private key. In other cases, you must define a client secret. See Client Authentication specifications for more information.
    • Environment ID: The environment identifier registered within the IdP.
    • Environment Secret: The environment secret registered within the IdP.

    The following fields are required for the SAML protocol:

    • Service Provider Entity ID: The unique identifier used to identify requests from a service provider. By default, this setting is set to the realm's base URL <root>/auth/realms/<realm_name>.
    • Single Sign-On Service URL: The endpoint that starts the authentication process. The value of this field is specified by your SAML IdP, if they publish an entity descriptor.

11. Click Save.