Configuring Single Sign-On on Azure

Prerequisites

• Azure Premium subscription.
• Global administrator privileges on the Azure portal.

Step 1: Add Amplify as an Enterprise Application

The first step is to add Amplify as an Enterprise application so that Single Sign-On can be set up. If this has already been done, move to step 2.

• On the Azure portal, click on Azure Active Directory in the left pane. If it has not been favourited, use the All Services option to search for it.
• Click on All Applications , then New Application. In the Add your own app section, click on the 'Non-gallery application' tile.
• Type in the name of the app in the Name text box, and click on Save. 

         

 

         

                            Adding a new non-gallery application

Step 2: Configure Single Sign On for Amplify on Azure

On successful creation of the application, Azure will redirect to the application settings page. Click on Single Sign-On on the application's pane. This will bring up the settings with four different sections.

Section 1 - Basic SAML configuration

• Set Identifier (Entity ID) as the Amplify instance URL.
• Set 'Reply URL (Assertion Consumer Service URL)' to be 'users/saml/auth' appended to the Amplify instance URL.

         

                                                           Screenshot showing the basic settings of Single Sign On

Note: Replace your-instance with the actual instance name.

Section 2 - User attributes and claims

Set the 'Name identifier value' to something that will uniquely identify a user. In most cases, user.mail would work.

Amplify requires the user email and user name attributes. To set these up, click the edit icon in the User attributes and claims section.

• Click on Add Claim, and add the 'email' attribute as shown in the screenshot. It is mandatory that 'email' should be all lowercase. 
• In most cases, the 'userprincipalname' is the email. In some cases, it might just be 'user.mail'. Please verify which source attribute holds the user email before setting this up.
• Namespace should be blank.
  
  

              

                                                   Screenshot of creating the 'email' attribute. 

• Click on the Add Claim again, and add the 'name' attribute as shown in the screenshot. Just as with the 'name' attribute, it is compulsory that 'name' should be all lowercase.
• Set up the name attribute in the format 'FirstName LastName' (Eg: 'Michael Bluth')  
• Namespace should be blank.
• Separator is one blank space.
  
  

               

                     Creating the 'name' attribute in the format 'FirstName LastName'

 

         

                                                   Section 2, after the email and name attributes, have been set up.

 

If the attributes are set up correctly, without namespaces, and the attribute names in all lowercase, the attributes in SAML response from Azure look something like this.

  

Section 3 - SAML Signing certificate

Click on the Download link next to the 'Federation Metadata XML'. You can use this to configure SSO on the Amplify app.

    

                                                                 SAML certificate download section

Section 4: Set up Amplify

This section has the login, logout and the Azure AD Identifier URLs. These URLs can be used to configure SSO on Amplify.

                                                                                        Set up Amplify section

Step 3: Add Users to AD

Now that SSO has been successfully configured on Azure, the next step is to add users to the AD group. The users in this group will then have access to Amplify.

From the application's pane, click on Users and Groups (just above the Single Sign-On option).

• Click on Add User to add a user. Search for and add the user. Select a role for the user.
• Repeat the process until all users who will have Amplify access have been added.

Step 4: Configure  Amplify to work with Azure SSO

Here, you can configure single-sign-on support using the SAML protocol. The Authentication tab can be found under the Administration section in Amplify

Main Settings

• Create a user if the user does not exist - This controls whether users should be automatically created in Amplify the first time they attempt to log in. Turn this off if you would like to limit who can log into Amplify.
• Update the user's attributes after successful login - This updates the user's name if it changes in the SAML provider.

SAML Provider Settings

Click Edit Provider to view the settings for the SAML provider.

• Status - The status of the SAML provider.
  • If Disabled, it is unused.
  • If in Test Mode, end-users won't see the SAML sign-in button on the login screen, but the configuration can be tested to ensure all is correct before enabling it completely.
  • If Enabled, users will see the SAML sign-in button on the login screen. This is unavailable unless Test Mode has been activated.
• Name - Give your SAML provider a useful name. This will be shown to users on the login screen.
• Provider Information - Many SAML providers give you a metadata file in XML format that contains all of the required settings. If you have this file or a publicly accessible link to it, enter that here, and it will pre-fill the settings. If you want to view these settings or enter them manually, click the Advanced toggle.

• IDP Entity ID - The entity ID of the SAML provider. This is commonly in a URL format.
• Login URL - The URL to which Amplify will redirect users when signing in
• Logout URL - The URL to which Amplify will redirect users when signing out
• SAML Signing Certificate - The certificate used to encrypt communications to the SAML provider. This should be in X509 format.

Attributes

Amplify requires that attributes for email and name be provided.

• For the "email" attribute, use the attribute name email
• For the "name" attribute, use the attribute name: name OR both givenName AND surname

When in Test Mode, Amplify will listen for sign-in attempts and verify that it receives the correct attributes. This happens automatically, and no page refresh is required.

To begin testing, enter the settings as above and change the status to Test Mode. Click Save. Amplify then begins listening for sign-in requests.

In Amplify, a link is displayed above the attributes table.

Copy this link, then open a different browser or a private browsing window and paste in the URL. This must be a different browser or private tab because the browser you are currently using contains a pre-existing sign-in cookie. If all is configured correctly, this should redirect you to your SAML provider, allowing you to sign in.

If the SAML provider gives the right attributes, the validation table will update to include green check marks next to the attributes given. Note, Amplify will continue to listen for sign-in requests for as long as this page is open in your browser.

It also shows a section called Last Sign-in Attributes which lists all of the attributes your SAML provider is giving Amplify.

This is useful when debugging an invalid response.

When testing is successful, you may now set the status to Enabled. When doing so, a new checkbox will appear at the bottom of the form, called Prevent existing users from logging in locally. If checked, it will ensure that existing users (if there are any) will not be allowed to log in with their Amplify email and password. Instead, they will be required to log in via SAML at all times.

 

Users will now see the "Log in with ..." button on the login screen.