Purpose

This document provides instructions on how to set up and configure Active Directory Federation Services (ADFS) for OUTSCAN or HIAB using Security Assertion Markup Language (SAML) protocol.

Introduction

Active Directory Federation Services (ADFS) provides users with authenticated Single Sign-On (SSO) access to applications unable to use Integrated Windows Authentication (IWA) through Active Directory (AD).

Setting up ADFS

To set up ADFS with OUTSCAN follow the steps in this document.

Note

When setting up the ADFS, note that trusted certificates at the front-end machine can be updated at regular intervals requiring an update of the ADFS configuration.

OUTSCAN or HIAB Configuration

In order to configure OUTSCAN or HIAB to use ADFS as identity provider, you need to perform the following steps:

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

Retrieve Identity Provider Metadata file

ADFS is providing an URL to download the SAML Metadata file. Simply open the following URL in a browser and save the file locally.

The URL is as follow: https://<ADFS_FQDN_OR_IP>/FederationMetadata/2007-06/FederationMetadata.xml

Adjust Identity Provider 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.

Setup 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.

Note

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:

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



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

    OptionDescription
    EnabledSelect 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 must can not use uid as Subject attribute, but you can use any other string (such as emailAddress).

    Note

    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.

    Note

    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 MetadataClick this button to display the currently uploaded metadata of the Identity Provider.
    SP MetadataClick on this button to display the service provider’s metadata.
  3. After enabling the required settings, click Save to save the current settings.
  4. Click Reset to fully remove the current settings. This disables the integration.


Enable the ADFS Integration on OUTSCAN

Note

Make sure that the previous section has been performed before continuing.


  1. Upload the updated metadata from ADFS as Get Metadata from file.
  2. If the ADFS configuration is set to use SHA-1 as Secure hash algorithm, then change Signature hash algorithm from the default SHA-256 setting to SHA-1.

  3. Click Save.
  4. Log out.


Check ADFS Configuration for Secure Hash Algorithm

To find out the settings for Secure hash algorithm configured in the Relying Party Trust in the ADFS configuration, edit the Properties and open Advanced tab to display this setting.

Secure hash algorithm


Download OUTSCAN Metadata

  1. Log in on https://outscan.outpost24.com or your HIAB.
  2. Go to Main Menu > Settings > Integration.
  3. Select the Identity Provider tab.
  4. Click SP Metadata at the bottom of the Integration Settings window.
  5. Click Save.
  6. Log out.

Configure ADFS Relying Party Trust

  1. Open ADFS Management.
  2. Click Add Relying Party Trust.
  3. Select Claims aware.
  4. Click Start.
  5. Select Import data about the relying party from file.
  6. Select the OUTSCAN metadata file.
  7. Click Next.
  8. Change Display name to Outscan, this will be the name of the Relying Party Trust.
  9. Click Next.
  10. Choose Access Control PolicyPermit everyone is default.
  11. Click Next.
  12. Review settings and click Next.
  13. Click Close.
  14. Select Relying Party Trust with name Outscan.
  15. Click Properties.
  16. Select the Identifiers tab.
  17. Add https://outscan.outpost24.com/opi/XMLAPI as Relying party identifier.

    Note

    The Identifiers tab contains a line like the following https://outscan.outpost24.com/opi/XMLAPI?ACTION=SAMLRESPONSE&UUID=1c428568-91ff-4c40-8537-d0d523b22ed3 where 1c428568-91ff-4c40-8537-d0d523b22ed3 is actually the <customeruuid> value. 
    The <customeruuid> is required when setting the claims, so it is recommended that you extract our <customeruuid> value from here.

  18. Select the Advanced tab.
  19. If SHA-1 is required change the Secure hash algorithm to SHA-1.
  20. Click Apply.
  21. Then click OK.

Configure ADFS Authentication Methods

  1. Open ADFS Management.
  2. Select Authentication Policies or if that does not exist, expand Services and select Authentication Methods.
  3. Click Edit for Primary Authentication Methods.
  4. Make sure Forms Authentication is enabled for section Intranet.
  5. Click Apply.
  6. Then click OK.

Disable ADFS Revocation Checks

  1. Open PowerShell prompt.
  2. Run command:

    Get-AdfsRelyingPartyTrust -Name Outscan | Set-AdfsRelyingPartyTrust -SigningCertificateRevocationCheck None -EncryptionCertificateRevocationCheck None


    Disable ADFS Revocation Checks

Configure ADFS Claim Rules

  1. Open ADFS Management.
  2. Select Relying Party Trust with name Outscan.
  3. Click Edit Claim Issuance Policy.
  4. Click Add Rule.
  5. Select Send Claims using a Custom Rule.
  6. Click Next.
  7. Enter rule name Create session identifier.
  8. Enter the following in the custom rule field:

    c1:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"] && c2:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant"]
    => add(store = "_OpaqueIdStore", types = ("https://outscan.outpost24.com/internal/sessionid"), query = "{0};{1};{2};{3};{4}", param = "useEntropy", param = c1.Value, param = c1.OriginalIssuer, param = "", param = c2.Value);

    Note

    outscan.outpost24.com can be changed to a local address in self-hosted environments.

  9. Click Finish.
  10. Click Add Rule.
  11. Select Send Claims using a Custom Rule.
  12. Click Next.
  13. Enter rule name Create transient name identifier.
  14. Enter the following in the custom rule field:

    c:[Type == "https://outscan.outpost24.com/internal/sessionid"]
    => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, 
    Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient", 
    Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "https://outscan.outpost24.com/opi/XMLAPI?ACTION=SHOWSPMETADATA&UUID=<customeruuid>");

    Note

    outscan.outpost24.com can be changed to a local address in self-hosted environments.

    <customeruuid> must be replaced by the customer uuid value that matches your integration use case. You can find your customer uuid value in identifiers tab as mentioned earlier in a note.

  15. Click Finish.
  16. Click Add Rule.
  17. Select Send LDAP Attributes as Claims.
  18. Click Next.
  19. Enter rule name Send uid.
  20. Select Attribute Store.
  21. Select the LDAP field that contains the Outscan username (like SAM-Account-Name) as LDAP Attribute.
  22. Enter uid as Outgoing Claim type.
  23. Click Finish.
  24. Click Apply and then OK.

Test the Integration

SP Initiated SSO, for example from Outpost24 OUTSCAN/HIAB

  1. Go to https://outscan.outpost24.com/ or alternatively to https://<hiab-ip-address>/) 
  2. Enter your username.
  3. Press on Single Sign-On.
  4. Enter your credentials on the ADFS page you have been redirected to.
  5. Press Sign In.
  6. You are redirected back to OUTSCAN and authenticated.


Note

If 2-factor authentication is enabled on OUTSCAN, you are required to provide it before you are logged in.

IdP Initiated SSO, for example from the ADFS Web Portal

  1. Login to the ADFS Web Portal.
  2. Select the application you want to access for example Outpost24 OUTSCAN/HIAB.
  3. Authenticate to ADFS.
  4. You are redirected to Outpost24 NetSec or Portal UI depending on your identity provider settings.

Tested version

OSVersionBuildADFS VersionStatus
Windows Server2016
3.0

WORKING

Windows Server2019 Datacenter Edition1776310.0.17763.1131

WORKING

References

https://docs.microsoft.com/en-us/windows/desktop/srvnodes/active-directory-federation-services




Copyright

© 2022 Outpost24® All rights reserved. This document may only be redistributed unedited and unaltered. This document may be cited and referenced only if clearly crediting Outpost24® and this document as the source. Any other reproduction and redistribution in print or electronically is strictly prohibited without explicit permission.

Trademark

Outpost24® and OUTSCAN™ are trademarks of Outpost24® in Sweden and other countries.