This article contains the following sections: 

• Embrace x HelloID
• Configuration

Embrace x HelloID

Embrace, HelloID & Microsoft 365 – The complete digital workplace portal

HelloID is a Netherlands-based software provider that creates Enterprise-ready Workspace Management and Enterprise Service Catalog solutions.  Make Embrace even more complete by displaying applications with the HelloID integration. 

Depending on the role you have in the organisation, you get access to certain applications in the software catalogue. Once HelloID is configured, you can automatically launch applications from Liquit and add applications from your Social start page. Currently, this is a widget; from Q4 onwards, we will provide a much nicer application launcher. For more information, see: Applications (Embrace, Liquit, HelloID) - how and what [add-on] 

Configuration

This document provides an overview of what that support consists of and how it should be configured. Currently, we support the following for HelloID:

• Authentication
  • General configuration
  • Web.config configuration
  • External users
• Application widget
  • Troubleshooting

From R41 onwards, we also support HelloID in combination with the Office365 connector. See the paragraph below for more info. 

Authentication

General configuration

See SAML2 Authentication for a general description of how SAML2 should be configured.

HelloID can be configured based on automatic configuration.

The data required for this can be managed in the HelloID admin portal (/admin, for example https://malengo-dev001.helloid.com/admin). In the HelloID admin portal, Embrace must be created as an application. There is a template available in HelloID for this. Then the data we need for the Embrace configuration will be available there.

HelloID does not work with role claims. So whether someone is an administrator is managed in Embrace. Therefore, after configuring HelloID, it may be that you are no longer an administrator in Embrace with the HelloID username. See SAML2 Authentication for solutions to this.

Web.config configuration

Authentication must be set to none:

<authentication mode="None" />

The following 4 appsettings must be included:

HelloID metadata button

Furthermore, the correct credentials with the correct mapping must also be created in the HelloID portal. Credentials in HelloID are SAML attributes / claims. The correct mapping should look approximately as follows:

These are the minimally required credentials, along with first and last name. Deviations are allowed here. Only the HelloID GUID must not be changed; it must always be as in the screenshot above, otherwise the application widget will not work. It is recommended to fill the NameID with the AD-SID so that the AD push sync can be used if desired.

See SAML2 Authentication for which other attributes can also be configured (the optional ones are often also very desirable).

For questions and more information about mapping the correct credentials, it may be good for the customer to contact HelloID.

External users

• See the following documentation if the customer wants to work with external users: External users in combination with 3rd party Identity Providers
• In case of Office 365 1-on-1 see Office 365 - 1 on 1 connection about how to deal with external users.

Application widget

There is a widget available in Embrace that shows all HelloID applications a user has rights to in HelloID. It looks approximately like this:

To use this widget, users must log in to Embrace via SAML2 / HelloID.

Furthermore, Embrace must have an API key from HelloID. This can be done in the HelloID admin environment at /admin/apikeys. A new API key must be added here. An IP restriction can optionally be specified based on the IP address of the Embrace web server.

These details must then be entered in Embrace environment management under HelloID connections:

The position of the widget in the sidebar cannot be changed.

Only after the above data has been entered will the widget be made available. Check the Embrace log files if things do not work.

HelloID in combination with Office 365 connector (R41)

If the Office 365 connector is used, Embrace needs an OAuth token from Office 365. Normally, Embrace obtains this automatically when "Entra ID OpenID Connect" authentication is used. But it is now also possible for Embrace to obtain this token via HelloID. This is done via an On Behalf Of (OBO) token. 

Basic configuration:

• For the configuration of HelloID, the standard procedure as described in this document can be used.
• In addition, Office 365 must be configured as usual: Office 365 - 1 on 1 connection
• And the Entra ID authentication: Entra ID

In addition, further/deviating configuration must be carried out:

• Perform the steps as described by HelloID (some of these steps may already have been executed; if in doubt, contact HelloID):
  • document 1: https://docs.helloid.com/hc/en-us/articles/360013152200-How-to-Configure-Azure-AD-as-a-OAUTH-Identity-Provider-Azure-AD-Session-Integration
  • If there are questions or problems, contact HelloID. Embrace-specific data for the above HelloID configuration:
     
    • Additional scopes are not needed (mentioned in document 1)
    • For the On Behalf Of scope, only user_impersonation is needed. So something like: api://f946aada-8c06-4232-b675-3f91f2ca3bf4/user_impersonation (mentioned in document 1)
    • HelloID Credentials. Apart from the usual credentials, there are the following deviations:
      • Embrace needs a credential named onbehalfoftoken containing the Azure access_token
      • The NameID must be the objectId/oid of Entra ID
• In the web.config, the appsettings of HelloID must be included as always with a HelloID connection.
• In addition, Embrace also needs the appsettings as described with the Office 365 connector. The only exception is that the appsetting UseOpenId must be set to false. 

Ultimately, the following appsettings must be present:

<!-- Entra ID -->
<add key="embrace:Azure:Authority" value="" />
<add key="embrace:Azure:ClientId" value="" />
<add key="embrace:Azure:ClientSecret" value="" />
<add key="embrace:Azure:UseOpenId" value="false" />

<!-- HelloID SAML -->
<add key="embrace:Saml2:MetadataAddress" value="" />
<add key="embrace:Saml2:ConsumerUrl" value="" />
<add key="embrace:Saml2:Issuer" value="" />
<add key="embrace:Saml2:SignOutUrl" value="" />

Troubleshooting

• HelloID widget. If the widget gives an error, it is likely that the custom HelloID attribute/claim is not configured correctly in HelloID. You should find it back as custom:helloid in the PropertyStorages table.
• Previously, the NameID was used; this should now be filled with the AD-SID/objectSID. If this is indeed the case and has been corrected, you will notice that existing users can no longer log in and receive an error message that a user already exists. This is because changing the NameID causes all users to have a different externalid. You can solve this by removing (emptying) the externalid for everyone in environment management. An alternative solution is to set the externalid column to null for everyone in the persons table in SQL.
• Office 365 connector. Check the Embrace log files for clues. Also check the troubleshooting sections of the other documents on configuring Entra ID authentication and configuring Office 365 1-on-1.