Azure AD Identity Provider Configuration

Purpose

The purpose of this document is to provide set up information on the Azure AD integration.

Introduction

This document provides step by step instructions on how to connect the Outpost24 tools, OUTSCAN and HIAB with Azure AD in order to enabling Single Sign On capability. The SSO can be initiated from both Service Provider and Identity Provider sides: respectively from Outpost24 tools, OUTSCAN, HIAB and Microsoft Azure portal side, myapps.microsoft.com.

Getting the SP Metadata File

You will require the SP metadata file from the Outpost24 tool you wish to integrate with.

On the Outpost24 Tool

Navigate to Main Menu > Settings > Integrations > Identity Provider
Select the Enabled checkbox and click the SP Metadata button

Azure AD Configuration

Login to https://portal.azure.com.
Once in the portal, in the navigation bar search Active Directory.

Creating a new Enterprise Application

In the side bar navigation select Enterprise Applications.
Select the + New application button.
In the Add an application screen, select the + Create your own application button and in the left panel select the Non-gallery application, and give the application a name that is recognizable and click Add. Azure will create the application ready for configuration.
Customize your newly created enterprise by uploading the O24 logo. This logo is displayed on the myapps.microsoft.com portal and enhances the user experience.
1. In the Enterprise applications section select <OUTPOST24 HIAB>
2. Then select Properties.
3. Select the Logo.
4. Select a file containing the OP24 logo.
  Note
  
  The O24 logo file size can not exceed 100.4 kB.
  Allowed file formats
  - jpeg
  - jpg
  - gif
  - png
  - bmp

Setting up Single Sign On

In the Getting Started section select Set up single sign on and select the SAML option.
1. Select the Upload metadata file and navigate to the downloaded Outpost24 metadata file from the previous steps. This populates the fields under the Basic SAML Configuration view that you can Edit.
  
  Entity ID should show: https://<IP>/opi/XMLAPI?ACTION=SHOWSPMETADATA&UUID=<uuid>
  Reply URL should show: https://<IP>/opi/XMLAPI?ACTION=SAMLRESPONSE&UUID=<uuid>
  
  Important
  
  Sign on URL field should remain empty.
  
  Where IP is the <IP> of the Outpost24 Tool you are integrating with and where <uuid> is the universal unique identifier that identifies your account.
  
  OUTSCAN Configuration
  
  In case you are configuring this for OUTSCAN, <IP> value is the OUTSCAN FQDN: outscan.outpost24.com
Next you need to define Attributes and Claims.
1. Click Edit under the User Attributes and Claims section.
2. Click the + Add new Claim button.
3. Configure the following information in the Manage Claim screen.
  
  Name: uid
  
  Claim Name requirement
  
  Pay attention, that the Name for the claim match the Subject attribute you entered in the Identity Provider section of the Integrations Settings panel on HIAB/OUTSCAN (default being uid).
  
  Claim Name considerations
  
  uid is a reserved name in Outpost24 software to truncate the USERNAME to the part below the @ sign, meaning that if you want to use an email address as USERNAME, you can not use uid as Claim name, but you can use any other string (such as emailAddress).
  
  Namespace: can be left blank
  Source: Select the Transformation radio button
4. In the Manage Transformation pop up view enter the following information.
  
  Recommended settings
  
  Transformation: ExtractMailPrefix()
  Parameter 1: user.userprincipalname
  Those settings correspond to standard practice to be able to login with a USERNAME matching the part below the @ sign in the user's email address. For instance, if the user's email address is firstname.lastname@somedomain.com, then the user will be able to login using firstname.lastname as username once configured in HIAB/OUTSCAN.
  
  Claim Transformation considerations
  
  By default, Azure ID populates the User Principal Name of Identity section of a user with the email address when creating the user.
  Depending on your configuration, it may happen that this field is empty and that the email address of the user is set in the Email of the Contact Info section of the user. In this case, replace the Parameter.1 with user.mail.
  
  Custom advanced settings
  
  In order to create some custom advanced settings using some specific attribute or different transformation option, please ensure that all select fields and user.x value are properly populated for all the user in the Azure Active Directory.
  Please also ensure that the results of your claim configuration match the USERNAME for the HIAB/OUTSCAN user.
5. Click the Add button. The transformation field now show the configuration you just created.
6. Click the Save button.
  
  If you want to use an email address as USERNAME in Outpost24 software, create a Claim that does not use uid (which is a reserved name in Outpost24 software) as name and that refers to an attribute that contains an email address such as in the sample below:
  
  Example
  
  In this example the user emails registered on Azure AD (for example, User Contact info Email) match the user names set on Outscan | HIAB (main account and sub users) and the Subject attribute in Identity Provider view shall be set to 'companyEmail'.
  
  Note
  
  You can name the claim on Azure AD as you want (except 'uid' which is reserved word) then you must name the same in subject attribute of the Identity Provider view.
Grant users access to the enterprise application you have defined

Important: Grant access to the Enterprise Application

By default Azure AD, does not grant access to the Enterprise application to any user. The access have to be granted in the User and Groups section of the applications, by clicking on the + Add user/group button.
Return to the Outpost24 HIAB Application configuration screen.

OUTSCAN or HIAB Configuration

In order to configure OUTSCAN/HIAB to use OneLogin as identity provider, you need to achieve the following steps:

Retrieving the metadata file describing the identity provider
Adjust the metadata file (if needed)
Uploading the metadata file in OUTSCAN/HIAB

Retrieve Identity Provider Metadata file

Under section 3 of the SAML-based Sign On screen > SAML Signing Certificate. Download the Federation Metadata XML file. You receive a XML file which is named the name of the application you have created in Azure.

Adjust Identity Provider Metadata File

To integrate an Identity Provider (IdP) in OUTSCAN or HIAB, you have to upload the SAML Metadata file describing the IdP. This file must comply to the SAML standard.

Upload the SAML Metadata File

Open the SAML Metadata file retrieved from the Identity Provider (IdP) and check that:

The file contains the XML tag: <?xml version='1.0' encoding='UTF-8'?>

XML tag consideration

If the XML tag is not present, just add the following tag <?xml version='1.0' encoding='UTF-8'?> at the beginning of the file.

The EntityDescriptor section contains validUntil attribute

validUntil attribute consideration

If this attribute is not present, just add it using the following format: validUntil="YYYY-MM-DDTHH:MM:SS"

A valid SAML Metadata file should looks like the following

SAML Metadata file consideration

Uploading the file in its current state will result in an error.

Set Up Identity Provider

An Identity Provider (IdP) offers user authentication as a service. It is a trusted provider that allows the use of single sign-on (SSO) to access other application. SSO enhances usability by reducing password fatigue as passwords are maintained on your IdP.

To enable SSO on OUTSCAN or HIAB you must import meta-data from your IdP into the solution. You also need to export the service provider’s meta-data from OUTSCAN or HIAB and import it to your IdP.

While reading the response from IdP during signing in to our portal, we accept signed assertions with parameters. The parameters list which your IdP is returning in response must include your user name in a parameter. By default it is set to parameter named uid but you can set up to different parameter (eg Subject attribute).

To set up Identity Provider:

Go to Menu > Settings > Integrations and select the Identity Provider tab.

Provide the below information to enable Identity Provider (IdP):

Option	Description
Enabled	Select the Enabled checkbox to enable the protocol for single sign-on trusting another source to log in.
Use one or both of the following option to provide metadata of IdP:
Get metadata from file:	Select Identity provider’s metadata file by clicking the + symbol beside the field. Metadata contains information such as how it works, what type of login is acceptable and so on.
Get metadata from URL:	Provide a URL from which the OUTSCAN or HIAB (Service Provider) should fetch metadata from IdP.
Subject attribute:	Enter uid string if you want to use USERNAME that is not an email address. This field cannot be left empty. Subject attribute considerations uid is a reserved name in Outpost24 software to truncate the USERNAME to the part below the @ sign, meaning that if you want to use email address as USERNAME, you can not use uid as Subject attribute, but you can use any other string (such as emailAddress). The parameter name must be typed as expected in the SAML authentication response (one single word starting with lowercase and may include some upper cases (eg camelCase)).
Signature hash algorithm:	Select between SHA-256 or SHA-1.
Direct access to portal:	SSO binds you respectively to Portal UI or NetSec UI when box is checked or not checked. If 'Direct access to portal' appears in grey then you cannot use this capability unless you update the SP metadata on your Identity Provider. For that you need first to download the SP Metadata by clicking on SP Metadata button and then make sure to upload it on your IdP. Once done you can then select option to be directed to either NetSec or Portal UI. If 'Direct access to portal' appears in grey then only SP initiated SSO is available. If you need to enable IdP initiated SSO then you have to download the SP Metadata by clicking on SP Metadata button and then make sure to upload it on your IdP. Once done you can then perform Single Sign On from the Identity Portal side.
IDP Metadata	Click this button to display the currently uploaded metadata of the Identity Provider.
SP Metadata	Click on this button to display the service provider’s metadata.

After enabling the required settings, click Save to save the current settings.
Click Reset to fully remove the current settings. This disables the integration.

Note

Ensure that the Subject attribute in the integration settings match the claim name in Azure AD

Verifying Integration Functionality

SP initiated SSO, eg from Outpost24 tool

Navigate to the login screen for the Outpost24 Tool
Enter the Outpost24 username (part below the @ sign in the user's email address as previously recommended settings) of the user added to the Outpost24 Application within Azure
Click single sign on and you will be redirected to login via the Azure portal.

The users AD account will need to be added to the Outpost24 Application in Azure to successfully login.

IdP initiated SSO, eg from myapps.microsoft.com

Login to myapps.microsoft.com.
Click on <OUTPOST24 HIAB> and you are redirected to Outpost24 Application, depending on settings to either NetSec UI or Portal UI.