Purple Portal SSO using Azure

Overview

This document describes how to create and set up a SAML authentication provider for Purple portal login with Azure.

The steps will guide you through creating a new Azure enterprise application for SSO (Single Sign On) and a Purple authentication for Azure so your users can log in to Purple portal via Azure.

Step 1 - Create a new Azure enterprise application

The first step is to create a new enterprise application in Azure for the Purple authentication with Azure.

1. Log into Microsoft Azure as an account administrator
2. Navigate to ‘Microsoft Entra ID’
   
   
   
3. Within ‘Microsoft Entra ID’ create a new ‘Enterprise application’
   
   
   
4. Within ‘Enterprise applications’ create a ‘New application’
   
   
   
5. Within the ‘Entra Gallery’ click on the ‘Create your own application’ option
   
   
   
6. Give your new application a name and click ‘Create’
   
   
   
7. On the overview for your new application choose ‘Set up single sign on’
   
   
   
8. In the ‘Single sign on’ options for your new application select ‘SAML’
   
   

Step 2 - Obtain SAML authentication values for the Azure application

Before we can set up the integration with Purple we need to obtain the following information from the new Azure application: 

• Entity Id
• Login URL
• Logout URL

These values can be obtained in the SAML setup for your application in the Set up Portal Azure SAML section.

1. Obtain the ‘Entity Id’
   
   Copy the value of the ‘Microsoft Entra Identifier’ and save it in a safe place.
    
2. Obtain the ‘Login URL’
   
   Copy the value of the ‘Login URL’ and save it in a safe place.
    
3. Obtain the ‘Logout URL’
   
   Copy the value of the ‘Logout URL’ and save it in a safe place.
    

You should now have a set of values similar to the following:

Step 3 - Create your Azure Purple authentication in Launchpad

We now need to create the new Purple Azure authentication in Launchpad.

1. Login to Launchpad and navigate to ‘Settings’
   
   
    
2. In ‘Settings’ click on ‘Add authentication’ to create a new authentication
   
   
    
3. Enter a name for your new Azure SAML authentication
   
   
   
4. Enter the ‘IDP Entity ID’
   
   This should be the ‘Entity ID’ for your application that you obtained in the previous step. This can be copied and pasted into the field e.g.
   
   
5. Enter the ‘Sign in URL’
   
   This should be the ‘Login URL’ for your application that you obtained in the previous step. This can be copied and pasted into the field e.g.
   
   
   
6. Enter a ‘X509 Signing Certificate’ value
   
   At this stage enter a temporary value of ‘To be obtained from Azure’. We will set this value in a later step.
   
   
   
7. Enter the ‘SIgn out URL’
   
   This should be the ‘Logout URL’ for your application that you obtained in the previous step. This can be copied and pasted into the field e.g.
   
   
    
8. Click ‘Save’ to create the new authentication

Step 4 - Configure your Azure application with the Purple authentication

After saving your new Azure authentication in Launchpad the next step is to configure your Azure application with the Purple service provider details.

You will now notice that your Azure authentication in Launchpad displays Service Provider Details.

1. In the Azure Portal In the SAML configuration for your application navigate to the ‘Basic SAML Configuration’ section and click ‘Edit’
   
   
    
2. Add the Identifier (Entity ID)
   
   Copy the Entity ID URL from the Launchpad Service Provider Details and add it as a new Identifier.
   
   
   
3. Add the ‘Reply URL’
   
   Copy the ACS URL from the Launchpad Service Provider Details and add it as the Reply URL.
   
   
4. Add the ‘Logout URL’
   
   Copy the Single Logout URL from the Launchpad Service Provider Details and add it as the Logout URL.
   
   
5. Save the changes

Your Azure SAML Configuration should now look similar to the image below.

Step 5 - Download the x509 certificate used by the Azure application 

After saving the SAML configuration in Azure an X509 certificate will have now been generated for the application. We now need to download the raw certificate.

Within the main Overview for the Azure application locate section 3 named SAML Certificates and click on ‘Download’ for the Certificate (Raw) option. 

Step 6 - Update the x509 certificate for the Purple authentication 

Back in Launchpad, ‘Edit’ your new Purple Azure authentication and copy and paste the raw certificate content that you downloaded into the X509 Signing Certificate field.

And Save the change.
 

Step 7 - Ensure you have set up users in Purple for your Microsoft accounts

Note that user accounts will need to be set up in Launchpad for any of your organisation’s Microsoft user accounts that will authenticate with your new Purple Azure authentication. The integration uses email addresses to identify users between Microsoft and Purple.

When authenticating successfully through Azure the Microsoft user’s email address is used to find a corresponding Purple user account. If a Purple user account is not found for the Microsoft user email address then the authentication with Purple will fail.

New Purple user accounts for your organisation’s Microsoft users can be added via Launchpad > Users as required.

Step 8 - Enable the authentication

In Launchpad navigate to Settings and enable the new Azure authentication within the list to make it ‘Active’.
 

The authentication can now be tested by logging in to Launchpad or your WiFi Portal. The Purple login screen will now provide an additional option to ‘Sign in with Azure’.
 

Troubleshooting

Below are some common problems that may be encountered when setting up the Purple authentication with Azure.

1. When trying to login in to Azure via Purple the user receives an error message that the application was not found 
   
   
   

This can be resolved by ensuring the ‘Identifier’ is set (seen in Step 4) for the Azure application. The value needs to be the Portal authentication ‘Entity ID’ value from the ‘Service Provider Details’ seen in Launchpad.

2. When trying to log in to Azure via Purple the user is ‘blocked’ from authenticating with the Azure application
   
   
   
   

This can occur when the Microsoft user has not been added to the ‘Users’ for the Azure application or is not part of a user group which has access to it.

In Azure visit ‘Users and Groups’ for the application and grant access for the user attempting to sign in via ‘Add user/group’  e.g.

3. After authenticating the user receives a ‘TechnicalError’ message



Ensure that the X509 certificate for the Purple authentication is the current certificate used by the Azure application. See Step 5 for details on how to obtain the current raw certificate for your Azure application and Step 6 for how to add it to your Purple Azure authentication in Launchpad.

4. After authenticating the user receives a ‘UserNotFound’ error message.



A user account was not found in Purple for the email address of the Microsoft user who logged in via Azure. Check that there is an active user account for the Microsoft user in Purple for the email address of the Microsoft user. See Step 7 which includes notes about this dependency.