Configure Azure ADFS

Configure SAML authentication with Microsoft Azure ADFS

Polarity-specific setup instructions can be found below.

Azure - App Creation

1. Navigate to the Azure Active Directory Admin Center 
   1. https://aad.portal.azure.com/
2. From the left navigation menu select "Applications" -> "Enterprise applications"  ->  "New Application" -> "Create your own application".
3. Name your app (e.g., "Polarity") and select the radio button for "Integrate any other application you don't find in the gallery (Non-gallery)".

Azure - Single Sign On

1. Once the application is created select the option to "Set up single sign on".  You may also find this option in the left navigation menu.
2. Select the "SAML" single sign-on method.

Basic SAML Configuration

1. In the "Basic SAML Configuration" block, click on the "Edit" icon
2. On the Basic SAML Configuration page fill in the Identifier and Reply URL as specified below.
   1. Identifier (Entity ID)
      1. https://<your-polarity-server-fqdn>
   2. Reply URL (Assertion Consumer Service URL)
      1. https://<your-polarity-server-fqdn>/sso/sp/consume/saml
   3. Sign on URL (Optional)
      1. Optional but can be set to:
         1. https://<your-polarity-server-fqdn>
         2. Replace <your-polarity-server-fqdn> with the fully qualified domain name of your Polarity server.
   4. Default Relay State
      1. https://<your-polarity-server-fqdn>/auth-success
   5. Logout Url (Optional)
      1. This is not needed
3. Once you have filled in the "Identifier" and "Reply URL" click on the "Save" button.

Attributes & Claims

1. Next click on the "Edit" button in the "Attributes & Claims block.
2. The page will show two columns.  A "Claim name" column and a "Value" column.  You will need to identify three required values when configuring SAML on the Polarity Server:
   1. An email value
   2. A username value
   3. A full name value
3. In most cases there will already be an email address (user.mail) and username (user.userprincipalname) claim.  
4. For the full name value we suggest creating a new claim by clicking on the "Add new claim" and filling in the following values:
   1. Name: displayname
   2. Source: Attribute
   3. Source attribute: user.displayname
5. Click on "Save" when done.
6. You will now save the "Claim name" for the user.mail, user.displayname, and user.userprincipalname values.  The Claim name for each of these values will be used when configuring SAML on the Polarity Server.

SAML Certificates

From the "SAML Certificates" block, download the "Federation Metadata XML" file.  We will use the content of this file when we configure the Polarity Server to use SAML Authentication.

Azure - Users and groups

We recommend controlling access to Polarity by granting access to the Polarity application in Azure via the Users and groups settings within the app.

Polarity Server SAML Configuration

1. Login to the Polarity Server as an admin via your browser and navigate to "Server Configuration" in the left navigation panel.
2. Click on the "Client Authentication" tab at the top of the page.
3. From the "Authentication Method" drop down select "SAML".
4. Once the SAML authentication method is selected you will need to fill in the following configuration details using information from the Azure app created in the previous steps.
   1. Polarity Server Fully Qualified Domain Name (FQDN)
      1. Fill in the FQDN of your Polarity Server to include the scheme (https://).  
   2. SAML Identity Provider (IdP) XML Metadata
      1. Paste in the content of the full Federation Metadata XML file that was exported from Azure. 
   3. Sign in button label
      1. You can customize the label on the SAML sign-in button by entering text here.
   4. Username Attribute
      1. The username value should must be a unique value for every user on the system. In most cases  you will want to use the user.userprincipalname value which will have the "Claim name":
         1. user.userprincipalname
         2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
      2. You can also use an email address for the username in which in most cases will be the "Claim name":
         1. user.mail
         2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
      3. When setting the Username attribute in the Polarity SAML configuration you will only provide the last segment of the claim name. 
         1. As an example, if you wanted to use the claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name you would only enter the value name into Polarity.
            IMPORTANT!

            Be sure to only use the last segment of the "Claim name" when configuring attributes within Polarity.
   5. Email Attribute
      1. The email must be a unique and valid email for each user in Polarity. The Email Attribute will typically use the user.mail value from ADFS. 
      2. In most cases, the Email Attribute in Polarity use the following "Claim name":
         1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
      3. As we only use the last segment of the "Claim Name", you would set the Email attribute in Polarity to emailaddress.
   6. Full name attribute
      1. The full name attribute contains the user's given and surname. 
      2. In most cases you will want to use the value user.displayname. There is usually no default "Claim name" for the user.displayname attribute.  If you added this claim when configuring SAML within Azure then the "Claim name" would be displayname. 
      3. If you did not add a displayname claim when configuring SAML in Azure, you can pick either the user.givenname or user.surname values which are available by default in most cases.
         1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
              or
         2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
      4. As an example, if you wanted to use the surname claim the Full name attribute would be set to surname.
   7. Group attribute
      1. You can optionally set a "Group attribute" which is used to identify which groups the user belongs to. You can then authorize specific groups using the "Authorized groups regular expression" option.
      2. If you leave this blank, all authenticated SAML users will be able authorized to login to the Polarity Server.
         NOTE

         We highly recommend leveraging the "Users and Groups" permissions within Azure ADFS to control which users and groups have access to the Polarity application, rather than controlling access from the Polarity Server.

   8. Authorized groups regular expression
      1. Provide one or more groups separated by a pipe (|). More complex group matches can be accomplished with a custom regular expression.  The provided regex will be run against the provided "Group attribute" of the user.  If the regex passes, the user will be granted access to the Polarity Server.  
5. After entering the required options in Polarity, click on "Apply Changes" in the top right.  When you navigate to the Polarity login screen you should now see the option to login via your SAML Identity Provider.