Enabling SAML authentication of users

Contents

Enabling SAML authentication of users

Overview

Many organizations adopt Identity and Access Management (IAM) solutions to facilitate their employees access to business applications through a single corporate login. This technique is known as Single Sign-On (SSO) access control. SSO improves the overall security of the organization by reducing the number of passwords that employees have to remember and type in.

The Security Assertion Markup Language (SAML) is a standard for exchanging authentication and authorization information securely between parties, namely the service provider (an application that needs to authenticate users) and the identity provider (a system that issues assertions about user identity). SAML is widely used in organizations to implement SSO.

By leveraging SAML, let Nexthink users comfortably log in to both the Portal and the Finder (the service providers) through your existing corporate SSO solution (the identity provider).

Prerequisites

To enable SAML-based authentication of Nexthink users, you need:

  • An IAM corporate solution that supports SAML to provide single sign-on. In this document, find the instructions to configure Microsoft Active Directory Federation Services (AD FS). Other systems may require similar configuration.
    • As SAML identity provider, the IAM solution must support the HTTP Redirect Binding for the Portal to be able to initiate SSO.
  • A proper external DNS name for the Portal (not an IP address) that matches the address of the Portal for email digests.
  • Nexthink users whose authentication is externally managed; that is, whose username includes a @ character (e.g. [email protected]).
  • HTTP protocol disabled in the Portal, as combining HTTP with HTTPS may cause redirection issues in some web browsers. From the Web Console of the master Appliance, on the Portal tab, untick the option Enable HTTP under the General > Parameters section.

Procedure to enable SAML

To enable SAML authentication:

  1. Configure the Portal as SAML service provider.
  2. Configure Microsoft AD FS, or any other IAM solution, as SAML identity provider.
    1. Add the Portal as relying party (in SAML parlance, a service provider is a special case of a relying party that, in addition to receive and accept info from other parties, consumes SAML assertions to provide a service).
    2. Specify how to issue SAML claims for the Portal to consume.

Configuring the Portal as a SAML service provider

Because the Finder relies on the Portal for authentication, configuring the Portal as SAML service provider enables users to log in to both the Finder and the Portal through SSO.

To configure the Portal as service provider:

  1. Log in to the CLI of the Portal.
  2. Download the metadata XML file of the identity from AD FS (replace <ADFS> by the address of your AD FS server):
    wget \
    https://<ADFS>/FederationMetadata/2007‑06/FederationMetadata.xml
  3. Save the file as idp_entity_descriptor.xml in the configuration folder of the Portal:
    sudo mv FederationMetadata.xml \
    /var/nexthink/portal/conf/idp_entity_descriptor.xml
  4. Change the owner of the file:
    sudo chown nxportal:nexthink \
    /var/nexthink/portal/conf/idp_entity_descriptor.xml
  5. Optional: If the Portal has no configuration file yet, that is, if portal.conf does not exist in folder /var/nexthink/portal/conf, create it by copying the defaults from the sample configuration file:
    sudo -u nxportal cp /var/nexthink/portal/conf/portal.conf.sample \
    /var/nexthink/portal/conf/portal.conf
  6. Edit the configuration file of the Portal:
    sudo vi /var/nexthink/portal/conf/portal.conf
  7. Add a configuration line to it:
    1. Press Shift + G to go to the last line of the file.
    2. Press o to add a new line.
    3. Type in the following line:
      globalconfig.saml.enabled = true
    4. Press Esc and type in the following colon command to save changes an exit:
      :wq
  8. Restart the Portal:
    sudo systemctl restart nxportal

To troubleshoot SAML authentication, try changing the following advanced options in the configuration file of the Portal in the same way as shown above for the option to enable SAML. Read the error logs of the Portal in /var/nexthink/portal/log/*.err to find out possible causes:

Option Default value
globalconfig.saml.strict false
globalconfig.saml.want‑assertions‑encrypted true
globalconfig.saml.want‑assertions‑signed true
globalconfig.saml.signature‑algorithm "http://www.w3.org/2000/09/xmldsig#rsa‑sha256"
The operations described in this article should only be performed by a Nexthink Engineer or a Nexthink Certified Partner.

If you need help or assistance, please contact your Nexthink Certified Partner.

Configuring Microsoft AD FS as identity provider

As a reference, this example configuration of AD FS shows how to use the UPN of users in the email format as the SAML Name Identifier for the Portal. Other configurations are possible depending on the format in which you saved the names of the users in the Portal.

To configure Microsoft AD FS as SAML identity provider for the Portal:

  1. Log in to the Windows Server machine that runs AD FS as administrator.
  2. Open AD FS management console.
  3. Under Actions, select Add Relying Party Trust.... The wizard to add a trusted relying party (in this case, the Nexthink Portal as service provider) shows up.
    1. On the Welcome step, choose a Claims aware relying party.
    2. Click Start.
    3. On the Select Data Source step, select the option Import data about the relying party from a file.
      1. Open a web browser on the following address to download the metadata file from the Portal (replace <Portal> by the external DNS name of your Portal):
        https://<Portal>/saml/metadata
      2. Save the file portal-sp-metadata.xml, as proposed by the web browser.
      3. Close the web browser to return to the wizard dialog.
    4. Click Browse... to specify the location of the file with the Portal metadata. A file dialog shows up.
    5. Select the file just downloaded from the Portal and click Open. The file dialog closes.
    6. Click Next >.
    7. On the Specify Display Name step, type in a suitable name for the relying party (e.g. Nexthink Portal).
    8. Optional: Type in any additional information about the relying party under Notes.
    9. Click Next > repeatedly to skip the rest of steps in the wizard until you reach the Finish step.
    10. Click Finish to complete the addition of the Portal as a trusted relying party. The wizard closes.
  4. In the left-hand side tree, click Relying Party Trusts to get the list of trusted relying parties.
  5. Right-click the trusted relying party entry that represents the Nexthink Portal just added.
  6. From the context menu, select the entry to edit the policy for issuing claims:
    • In Windows Server 2016, select Edit Claim Issuance Policy....
    • In Windows Server 2012, select Edit Claim Rules....
  7. In the Issuance Transform Rules tab, click Add rule... to map the UPN of the user to the Name ID, which the Portal matches against the username field for authenticating . The wizard to add a new transform rule for claim issuance shows up.
    1. On the Choose Rule Type step, select Send LDAP Attributes as Claims under Claim rule template.
    2. Click Next >.
    3. On the Configure Claim Rule step, provide the following information:
      • Under Claim rule name, type in a suitable name for the rule (e.g. Map UPN to Name ID).
      • Under Attribute store, select Active Directory.
      • Under Mapping of LDAP attributes to outgoing claim types, select User-Principal-Name as LDAP Attribute and Name ID as Outgoing Claim Type.
    4. Click Finish
  8. Back to the Issuance Transform Rules tab, click again Add rule... to add a new rule to send the UPN as Name ID in the email format. The wizard to add a new transform rule shows up once more.
    1. On the Choose Rule Type step, select Transform an Incoming Claim under Claim rule template.
    2. Click Next >.
    3. On the Configure Claim Rule step, provide the following information:
      • Under Claim rule name, type in a suitable name for the rule (e.g. UPN as Name ID in email format).
      • As Incoming claim type, select UPN.
      • As Outgoing claim type, select Name ID.
      • As Outgoing name ID format, select Email.
      • Leave checked the option Pass through all claim values.
    4. Click Finish.
    5. Click OK to close the dialog to edit the claim rules.
  9. Right-click again the trusted relying party entry that represents the Nexthink Portal.
  10. Select Properties from the menu. The dialog to watch and modify the properties of the relying party shows up.
    1. Under the Advanced tab, select SHA-256 as Secure hash algorithm.
    2. Click OK to close the properties dialog.

After enabling SAML authentication, log in to both the Finder and the Portal using the corporate login method.

Alternate UPN suffixes in SAML authentication

When a user logs in via SAML authentication with the reference configuration for AD FS shown above, the UPN of the user is mapped to the Name ID returned by the identity provider. If the user logs in with an alternate UPN suffix, the identity provider returns the UPN with the fully qualified domain name as suffix.

For example, let us consider an organization that manages the following fully qualified domains:

  • us.acme.com
  • de.acme.com

The fully qualified name of the domains is used to define the UPN of the users:

To simplify user access though, administrators may define an alternate UPN suffix acme.com, so that users do not have to memorize lengthy subdomain names and levels. With this alternate UPN suffix, the resulting account names look like this:

Even if users log in with their alternate UPN suffix through SAML, the identity provider returns the UPN with the fully qualified domain name to the Portal instead. For instance, if user John Wick logs in to the Portal (or to the Finder) with the username [email protected], SAML authentication will issue a Name ID claim for user [email protected], which the Portal will then match against its stored usernames. Because the identity provider already carries out this transformation, the Portal does not try to map alternate UPN suffixes to fully qualified UPN suffixes when using SAML authentication, contrary to what it does in the case of authentication through Active Directory.

Therefore, for SAML authentication to work properly, the Portal must store usernames in the UPN format with the fully qualified domain name as suffix. Users provisioned from Active Directory are normally stored with the correct UPN.