Okta Identity Provider Configuration

Purpose

This document provides instructions to set up and configure Okta Identity provider (IdP) for OUTSCAN or HIAB using Security Assertion Markup Language (SAML) protocol.

Introduction

Okta is a Identity and Access Management (IAM) solution that add authentication service to applications across a wide variety of platforms using Single Sign-On (SSO) authentication scheme. Okta allows connections to any application and define how users sign in. When a user tries to authenticate, Okta verifies their identity and send the required information back to the application from which the login was initiated (Application initiated authentication).

Okta Configuration

This section describes the steps to configure Okta (IdP) by creating an application in order to integrate with OUTSCAN or HIAB solution.

Create an application

To create an application:

Login to Okta portal with administrative privileges and then navigate to Applications/Applications in the left menu as shown below:
Then click the Create App Integration button that will open a window to create a SAML application integration.
Select SAML 2.0 and then click the Next button. This open a new window to create the application.
Name the application and provide a logo and click on the Next button.
Once the general settings are entered, continue to the SAML configuration step where you need to add OUTSCAN or HIAB URL. Adjust both Single sign on URL and Audience URI (SP Entity ID) by replacing <OUTSCAN/HIAB_FQDN_OR_IP> with the FQDN or IP address of your OUTSCAN or HIAB setup in the following text:
- Single sign on URL
  
  SAML Settings
  
  https://<OUTSCAN/HIAB_FQDN_OR_IP>/opi/XMLAPI?ACTION=SAMLRESPONSE&UUID=<customeruuid>
- Audience URI (SP Entity ID)
  
  SAML Settings
  
  https://<OUTSCAN/HIAB_FQDN_OR_IP>/opi/XMLAPI?ACTION=SHOWSPMETADATA&UUID=<customeruuid>
  
  Note
  
  The <customeruuid> must be replaced by the uuid value that matches your account. You can find the customer uuid value in the SP metadata XML file that you downloaded from Outpost 24 OUTSCAN/HIAB by clicking on the SP Metadata button in Identity Provider integration window. The XML file contains several URLs with 'UUID=' pattern, just take the value from here. For instance a valid customer uuid is like this 1c428568-91ff-4c40-8537-d0d523b22ed3.
Your configuration should then look as follow:
To allow the OUSTCAN or HIAB application to properly identify the Identity during the authentication phase, you need to declare the same attribute in both OUTSCAN or HIAB and the identity Provider (IdP). In Okta, this can be done by adding an attribute as shown below.

Attribute Name considerations

The 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 attribute name, but you can use any other string (such as emailAddress).
Once done, you can preview the SAML assertion and then click the Next button.
After answering Okta Support question, click the Finish button to create the application.
Once you have created the OUTSCAN or HIAB application on Okta Identity Provider, you need to assign users or groups to this application. In our example below we are using a group that makes management easier.
Open the Assignments tab and click on the Assign button.
Select Assign to Groups to start assigning groups to the application.
Choose a group to assign and click on the blue Assign text.
When the users or groups has been assigned to the application, click the blue Done button.
Your assignment are now populated.

OUTSCAN or HIAB Configuration

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

To retrieve the IdP metadata file, you need to open the Sign On tabulation of your application.

Then scroll down to the SAML Signing Certificates section and then click on the Actions button menu to View the IdP metadata.

This opens a new page in your browser that you can save on your computer and reuse later while configure the IdP in OUTSCAN or HIAB software.

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.

Setting Up Identity Provider

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.

When setting up a SSO for a sub-user, the UID must be the same as the e-mail address.

Test the Integration

SP initiated SSO, for example from Outpost24

Go to https://outscan.outpost24.com. (or alternatively go to your HIAB https://<hiab-ip-address> if you integrate Okat with HIAB)
Enter your username.
Click on Single Sign-On.
Enter your username and password on the Okta page you have been redirected to.
Click Sign In.
You will be redirected to OUTSCAN and authenticated.

Note

If you have 2-factor authentication enabled on OUTSCAN, you must provide it before you log in.

IdP initiated SSO, for example from Okta

Login to okta <YourDomain>.okta.com.
Click on <Outscan/Hiab> to be redirected to Outpost24 OUTSCAN/HIAB
You are redirected to either NetSec or Portal UI depending on the settings you set in NetSec UI Identity provider integration window.

Reference

Okta SAML concepts overview: https://developer.okta.com/docs/concepts/saml/

Okta SAML integration: https://developer.okta.com/docs/guides/build-sso-integration/saml2/main/