Just-In-Time provisioning of user accounts

Overview

Manually adding users to Nexthink through the Portal may be a tedious and error prone operation, specially if you have a fair amount of users to add to your setup.

Thanks to the just-in-time (JIT) provisioning of user accounts, take advantage of the users and groups managed by your SAML identity provider to automatically create the required user accounts in the Portal when users log in for the first time.

In addition, user information is verified and access rights updated on every login. For instance, if the group membership of a user changes, the access rights of the user change accordingly.

Prerequisites

To provision users just-in-time with SAML, you need first to:

Have an admin account in Nexthink that is not SAML authenticated (local or AD account). This admin account will be required to complete JIT SAML configuration.
Enable SAML authentication of users in Nexthink.
Define user profiles in Nexthink.
Add users to your SAML identity provider and define groups of users.

Procedure and method

These are the main steps to provision users just-in-time with SAML:

Enable JIT provisioning of users through SAML in the Portal.
Instruct your SAML identity provider to convey group membership and personal information in the SAML assertions about a user.
Map user groups to user profiles in the Portal.

The idea is thus to assign profiles to users based on their group membership and update their personal information on every login. Depending on whether a particular user account already exists in Nexthink or not, the system does the following:

Group to profile mapping:	Successful	Unsuccessful
User account missing in Nexthink	Create user account in Nexthink: Username = Name ID Set profile based on group mapping Set full name and email Log the user in	Deny access to the user
User account exists in Nexthink	Update account in Nexthink: Update profile based on group mapping Update full name and email Log the user in	Deny access to the user Deactivate / Delete user account

In case of an unsuccessful mapping of a user group to a profile, the user gets its account:

Deactivated, if the user logged in to the system in the past.
Deleted, if the user has never logged in to the system before.

When deactivated, a user account still keeps the data associated to it, including modules, dashboards, etc. If a deactivated user later joins a properly mapped group and is thus reprovisioned, all associated data is recovered. In turn, if a user account is deleted, it loses all its associated data.

Enable JIT provisioning in the Portal

Configure the Portal to support the JIT provisioning of users:

Log in to the CLI of the appliance that hosts the Portal.
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
Edit the configuration file of the Portal: sudo vi /var/nexthink/portal/conf/portal.conf
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.jit-user-provisioning = true
4. Press Esc and type in the following colon command to save changes an exit: :wq
Restart the Portal: sudo systemctl restart nxportal

Advanced configuration

In case that your SAML identity provider does not allow you to modify the name of the attribute in the SAML assertions that conveys the required information, add the name that identifies that piece of information system (usually a URI) to the configuration file of the Portal. There is a dedicated entry for each one of the required assertions: full name, group membership, and email.

The default values in the configuration file of the Portal support the names used by AD FS and the ones that you supply when configuring Azure AD as indicated below.

CODE

fullname-attribute-names =
 [ "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
   "nexthink.fullname" ]
groups-attribute-names =
 [ "http://schemas.xmlsoap.org/claims/Group",
   "nexthink.groups",
   "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups" ]
email-address-attribute-names =
 [ "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
   "nexthink.email" ]

Adding group membership and personal information to SAML assertions

Configure your SAML identity provider to include the group membership and the personal information (full name and email address) of users in its SAML assertions, also known as claims in Azure AD and AD FS.

Configuring claims in AD FS

To configure the claims in Microsoft AD FS:

Log in to the Windows Server machine that runs AD FS as administrator.
Open AD FS management console.
On the left-hand side panel, under Trust relationships, select Relying Party Trusts.
Right-click the entry that you must have previously configured to define the Portal as a relying party.
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....
In the Issuance Transform Rules tab, click Add rule... to get the full name of the user in the SAML assertions. 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: nexthink.fullname
  - Under Attribute store, select Active Directory.
  - Under Mapping of LDAP attributes to outgoing claim types, select Display-Name as LDAP Attribute and Name as Outgoing Claim Type.
4. Click Finish
Back to the Issuance Transform Rules tab, click Add rule... again to add the groups of the user to the SAML assertions.
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: nexthink.groups
  - Under Attribute store, select Active Directory.
  - Under Mapping of LDAP attributes to outgoing claim types, select Token-Groups - Qualified by Long Domain Name as LDAP Attribute and Group as Outgoing Claim Type.
4. Click Finish
Back to the Issuance Transform Rules tab, click Add rule... for the third time to add the email address of the user to the SAML assertions.
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: nexthink.email
  - Under Attribute store, select Active Directory.
  - Under Mapping of LDAP attributes to outgoing claim types, select E-Mail-Addresses as LDAP Attribute and E-Mail Address as Outgoing Claim Type.
4. Click Finish.
Click OK to close the page for editing claim rules.

Configuring claims in Azure AD

To configure the claims in Azure AD:

Log in to Azure from your web browser https://portal.azure.com.
Click Azure Active Directory on the left-hand side panel.
Under Manage, select Enterprise applications.
Select the Nexthink Portal application that you must have previously configured.
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.
Click the pencil icon to the right of Groups returned in claim. The page Group Claims (Preview) shows up.
1. Choose Groups assigned to the application, as the groups associated to the user to be returned in the claim.
2. Select Group ID as the Source attribute to return.
3. Under Advanced options, tick Customize the name of the group claim.
4. As Name (required), type in: nexthink.groups
5. Click Save to return to the User Attributes & Claims page.
Click the button Add new claim to include the full name of the user in the issued SAML assertions. The page Manage user claims shows up:
1. As Name, type in: nexthink.fullname
2. Choose Attribute as type of Source.
3. As Source attribute, select: user.displayname
4. Click Save.
Click the button Add new claim to include the email of the user in the issued SAML assertions. The page Manage user claims shows up:
1. As Name, type in: nexthink.email
2. As Source attribute, select: user.mail or user.userprincipalname
3. Click Save.
Optional: Delete the claims not consumed by the Nexthink Portal.
Get the identifiers of the groups in Azure AD to map them to Nexthink profiles later.
1. Back to the main page of the Azure portal, click Azure Active Directory on the left-hand side panel.
2. Under Manage, select Groups. The list of active groups appears on the page Groups - All groups.
3. Select one of the groups that you wish to map to a profile in Nexthink.
4. On the left-hand side menu of the page, select Properties under Manage.
5. In the Properties page, under the General settings section.
6. Click the paper icon to the right of the Object ID field to copy the identifier of the group.
7. Paste the Object ID somewhere else (e.g. a text editor) and save it, so that you can reuse it later.
8. Click Discard at the top of the Properties page to go back to group selection and repeat the operation for as many groups as you need to map to profiles in Nexthink.

Mapping groups to profiles

To map the groups defined in your SAML identity provider to the profiles defined in Nexthink Portal:

Log in to the Portal with a local or AD admin account (see prerequisites above).
- Warning: Do not try to log in through corporate single sign-on with this account! As user groups are not mapped to profiles yet, the mapping will fail and the account might be deactivated (if not local).
Click the ADMINISTRATION drop-down menu at the top of the window.
Select Accounts under ACCOUNT MANAGEMENT. The page to manage user accounts appears.
Click the button SAML Groups at the top of the page.
Click the button Add group to set a new mapping.
1. Type in the name of a group in the column AD group name.
  - If Azure AD is your SAML identity provider, type in or paste the previously saved Object ID of the group.
2. Select an available user profile from the list in the Profile column.
  - If the profile is parameterized, choose the view domain of the users to be imported from the View list in the Profile Domain column.
  - Additionally, if the parameterized profile is of the administration type, choose the administration domain of the users to be imported from the Admin list in the Profile Domain column.
Optional: Repeat the previous step to add more mappings.
Click OK.

At login time, the Portal grants access to all users that are members of at least one of the mapped groups. The exact permissions of the user are determined by the assigned profile.

Determining mapping precedence

Because users may belong to more than one group, the order in which you specify the mapping of the groups is important. Namely, if a user belongs to two groups and both groups are mapped to different profiles in the Portal, the user gets assigned the profile that is mapped to the first group in the list.

RELATED TASKS