Configure Okta

Configure SAML authentication with Okta

Polarity SAML authentication should work with any identity provider (IdP) given the application is set up correctly within the identity provider's account. This guide walks through configuring Polarity SAML Authentication with Okta SAML 2.0.

Create Polarity Application in Okta

The first step to setting up SAML authentication is to create a new Polarity Application within Okta.  

General Settings

Navigate to "Applications" and click on "Create App Integration".   Select the "SAML 2.0" option and click "Next".  Fill in the settings as follows:

1. App name
   1. Polarity
2. App logo (optional)
   1. You can download and upload the Polarity logo from this link:
      1. https://assets.polarity.io/img/logos/logo-large.png
3. Click "Next" to go the next page of options

Configure SAML

1. Single sign-on URL(This is a required field) 
   1. https://<yourpolaritydomain>/sso/sp/consume/saml
      Note

      Use this for Recipient URL and Destination URL should be checked

2. Audience URI(SP Entity ID)
   1. https://<yourpolaritydomain>
3. Default RelayState(this is a required field) 
   1. https://<yourpolaritydomain>/auth-success
4. Name ID format
   1. EmailAddress
5. Application Username
   1. Email
6. Update application username on
   1. Create and update
7. Attribute Statements

   1. Name	Name format	Value
      username	Unspecified	user.login
      email	Unspecified	user.email
      fullname	Unspecified	user.firstName

8. Group Attribute Statements
   1. leave blank
9. Click "Next" and finish the Application setup
10. Navigate to the "Polarity" application in Okta and click on the "Sign On" tab at the top of the page.
11. On the right side find the button that says "View SAML setup instructions".  This page provides all the settings required when configuring SAML via the Polarity Server Configuration page. 

Configure SAML in Polarity

Now that the Polarity Okta Application has been set up we can configure SAML within Polarity using the SAML configuration values provided by Okta in the step above. To get to the SAML configuration page within Polarity navigate to "Advanced Settings" -> "Server Configuration" -> "Client Authentication" and then pick "SAML" from the drop-down menu:

Polarity SAML Options

1. Polarity Server Fully Qualified Domain Name (FQDN)
   1. Enter your Polarity Server's fully qualified domain name.
2. SAML Identity Provider (IdP) XML Metadata
   1. From the Okta configuration page, scroll to the bottom of the page and copy the entire contents of the IdP Metadata which is in XML format. 
   2. Copy and paste this XML into the SAML Identity Provider (IdP) XML Metadata field within the Polarity SAML configuration page.
3. Sign in button label
   1. You can modify the SAML sign in button label here with your preferred text.  The default value is "Sign in with SAML".
4. Username attribute
   1. username
5. Email attribute
   1. email
6. Full name attribute
   1. fullname
7. Group attribute (optional)
   1. This is the the attribute in the SAML assertion which specifies which groups the user belongs to (optional). If this field is left empty then no authorization checks will be made and all authenticated SAML users will be able to access Polarity. If an invalid attribute is provided no users will be authorized.
   2. If this attribute is provided and you would like Polarity to enforce authorization you should also fill out the Authorized groups regular expression option.
   3. If you are controlling access to Polarity via Okta Assignments leave this option blank and assign users to the Polarity Application via Okta.
8. Authorized group regular expression (optional)
   1. If provided, each group the user belongs to as specified by the Group attribute option will be matched against the provided regular expression. If any group matches, the user will be authorized to login to Polarity. The provided regular expression should not include leading or trailing forward slashes. In addition, the regular expression will be wrapped in ^(?: )$ to default to exact matches.
9. Save Options
   1. In the top right of the Polarity web interface, click on the "Apply Changes" button to save your new SAML configuration.

The Polarity sign in page will now have an additional "Sign in with SAML" button (possibly renamed if you modified the Sign in button label option).  When a user clicks on this button they will be redirected to Okta to authenticate.  If the user has been assigned access to the Polarity application in Okta, a new local account will automatically be created for that user and they will be logged into Polarity. 

Users that sign in via SAML cannot login with the local account as the account will be marked as "remote" within Polarity.  All password management for the account is done via Okta.