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

To call the integration APIs, create dedicated Nexthink local accounts instead. Make sure that you set a minimum complexity for the password of local accounts.

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.

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 either Microsoft Active Directory Federation Services (AD FS) or Microsoft Azure Active Directory (Azure AD). Other systems may require a similar configuration.

  • As a 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. jwick@acme.com). These accounts are automatically created if you provision users just-in-time with SAML.

• The HTTP protocol is disabled in the Portal, as combining HTTP with HTTPS may cause redirection issues in some web browsers. From the Web Console of the primary Appliance, on the Portal tab, untick the option Enable HTTP under the General > Parameters section.

Procedure to enable SAML

To enable SAML authentication for Nexthink:

1. Enable SAML in the configuration file of the Portal and change the default options if needed.

2. Configure Microsoft AD FS, Azure AD, or any other IAM solution, as a 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.

      • In the examples shown below, the UPN of the users is mapped to the Name ID in SAML to simplify the transition from Active Directory to SAML. Other configurations are possible depending on the format in which you saved the names of the users in the Portal, as long as the names include an @ character. For instance, you can use email addresses that do not necessarily match the UPN as Name IDs.

3. Configure the Portal as a SAML service provider and link it to your identity provider.

Enabling SAML authentication in the Portal

Edit the configuration file of the Portal to enable SAML as an authentication method:

1. Log in to the CLI of the appliance that hosts the Portal.

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

3. Edit the configuration file of the Portal:
   sudo vi /var/nexthink/portal/conf/portal.conf

4. 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 and exit
      :wq

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

Enabling SAML strict mode

When enabling strict mode for improved security, set the value of validate‑current‑url depending on your identity provider. The following combinations have been tested:

In some cases setting the value of globalconfig.saml.want-messages-signed to false allows proper SAML authentication. That parameter will instruct the Portal not to require a signed returned message from the IdP.

Configuring Microsoft AD FS as an 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.

To configure Microsoft AD FS as a 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.

Configuring Azure AD as an identity provider

To configure Azure AD as a SAML identity provider for the Portal:

1. Log in to Azure from your web browser https://portal.azure.com.

2. Click Azure Active Directory on the left-hand side panel.

3. Under Manage, select Enterprise applications.

4. Click the New application button preceded by a plus sign at the top of the window.

5. Under Add an application, choose the Non-gallery application tile.

6. On the panel Add your own application that appears to the right, type in the name of the application (for instance, Nexthink Portal) inside the Name field.

7. Click the Add button at the bottom of the panel.

8. On the left sidebar of the Enterprise application that you have just created, under Manage, select Single sign-on .

9. On the page Select a single-sign on method, choose the SAML tile. The page Set up Single Sign-On with SAML shows up.

10. Open a new tab in the web browser.

    1. Type in 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 tab to return to the page Set up Single Sign-On with SAML.

11. Click the button Upload metadata file at the top left corner of the page.

12. Select the metadata file portal-sp-metadata.xml that you have just downloaded from the Portal.

13. Click the pencil icon at the top right corner of the second tile to edit the User Attributes & Claims. The page to edit the claims appears.

    1. Ensure that the Name identifier value (that is, the Name ID returned by Azure AD) is the user principal name (UPN) in the email format:

       • user.userprincipalname [nameid-format:emailAddress]

    2. Close the User Attributes & Claims page.

14. On the third tile of the page SAML Signing Certificate, click the Download link associated with the last entry: Federation Metadata XML. You will use this file later to link the Portal to Azure AD as its SAML identity provider.

15. Click the pencil icon to the right of the same third tile to edit the SAML Signing Certificate:

    1. Verify that SAML assertions are signed using SHA-256 as a signing algorithm. On the page that shows up, you should read:

       • Signing option Sign SAML assertion

       • Signing algorithm SHA-256

    2. Close the SAML Signing Certificate page.

16. Back to the left sidebar of the Enterprise application that represents the Portal, under Manage, select Users and groups.

17. Click the button Add user to add users or groups that can log in to the Portal via SAML authentication.

Configuring a generic SAML identity provider

Although it is not possible to detail the configuration instructions for every SAML identity provider available in the market, the procedure to configure a compliant provider should not differ significantly from the two reference examples shown above.

When manually configuring a generic SAML identity provider, keep the following information at hand (replace <Portal> by the external DNS name of your Portal):

Configuring the Portal as a SAML service provider

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

To configure the Portal as a service provider:

1. Log in to the CLI of the appliance that hosts the Portal.

2. Get the metadata XML file of the identity provider:

   • When using AD FS as an identity provider, type in the following command by replacing <ADFS> by the address of your AD FS server:
     wget \ https://<ADFS>/FederationMetadata/2007‑06/FederationMetadata.xml

   • When using Azure AD as an identity provider, retrieve the Federation Metadata XML file that you downloaded while configuring Azure AD as an identity provider.

     1. Copy the file to the Portal appliance with your favorite SCP tool.

3. Save the file as idp_entity_descriptor.xml in the configuration folder of the Portal. Assuming that the original name of the file is FederationMetadata.xml, type in:
   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. Restart the Portal:
   sudo systemctl restart nxportal

After configuring the Portal as a SAML service provider, the selected users should be able to 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 or Azure AD 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 a 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:

• jwick@us.acme.com

• mkahn@de.acme.com

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:

• jwick@acme.com

• mkahn@acme.com

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 jwick@acme.com, SAML authentication will issue a Name ID claim for user jwick@us.acme.com, 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 a suffix. Users provisioned from Active Directory are normally stored with the correct UPN.

RELATED TASKS

• Logging in to the Portal

• Logging in to the Finder

• Setting the names of the Portal

• Sending email notifications from the Appliance

• Just-In-Time provisioning of user accounts with SAML

• Provisioning user accounts from Active Directory

RELATED REFERENCE

• Active Directory authentication