Setting up SAML2.0 SSO with Microsoft Entra ID

Most of our customers prefer to use the standard Entra ID login, as advised here. However, there may be specific reasons for preferring to use SAML based authentication, such as for user group based access control that is managed separately for each board. Here is a brief overview of the steps needed to configure the integration.

Please note that this integration is currently tested to only work with IdP initiated SSO, e.g. so that users would need to login via the Microsoft Enterprise App Gallery, or via a specialised login URL. For example, the native Teams application may not work with this method. As such, we recommend OAuth based Entra ID authentication for most customers!

Prerequisites

To complete the following steps, you will need:

A user account with appropriate admin permissions for Microsoft Entra ID settings (admin rights for Enterprise Applications)
A user with board or organization admin permissions to the desired HYPE board.

Creating an Entra ID Enterprise Application

We will start by creating an Entra ID Enterprise Application.

Step 1. Create a new Enterprise Application

Go to the Entra Gallery and choose "Create your own application"
Name your app and choose "non-gallery"

Step 2. Assign your desired users/groups for the application

Many simply choose all company as you can limit access control further within HYPE Boards, but you can pick whichever users or groups you wish to have access here.

Step 3. Start setting up single sign on

Click on the SSO tile illustrated above and then choose SAML from the provided options.

Step 4. Upload the HYPE Boards Federation Metadata file

To make the setup process easier, you can download HYPE Baords' prepared XML metadata file and then upload it to Entra to do the most of the configuration automatically.

You can download a copy from here, or get a copy from the access settings page of your HYPE board by choosing SAML2.0 and then choosing the option to create a new configuration.

Your Basic SAML configuration is now complete.

Step 5. Edit Claim rules

You will now need to add a new claim rule manually for UPN.

Choose "Add new claim"
Set upn as the name, and http://schemas.xmlsoap.org/ws/2005/05/identity/claims as the namespace.
Select user.userprincipalname as the source attribute.
Make sure to save your settings!

HYPE Baords also supports user_groups as another claim name. To add this claim, follow the same steps as above, and pick the matching source attribute matching your configuration. These groups can be used in HYPE Boards to limit access to a given board to only the specified groups.

To configure this, please choose "Allow listed users and users belonging to any of the following user groups" as illustrated in the screenshot below.

Setting up the integration in HYPE Boards

You're now ready to connect your Enterprise Application to HYPE Boards. Here are the steps for configuring the integration to a given board. For subsequent boards within the same organization, admins can reuse the same configuration, but choose to limit access to a subset of all users allowed to access the application.

Step 1. Go to access settings of your board

Navigate to the Login settings page of your HYPE board
Choose SAML2.0 and click "Connect to a SAML service"

Step 2: Fill in the values for the connection

To finalise the set up of the integration in HYPE Boards, you will need three values from the SSO page of your Enterprise Application page:

Login URL
Microsoft Entra Identifier (Entity ID in HYPE Boards)
Thumbprint (SAML certificate fingerprint in HYPE Boards)

Copy the values from here to the modal and choose an appropriate title for your login button and save your settings. Typically something like "Company Name login".

Step 3. Test the integration

You can easily test the integration by clicking the test button on your Enterprise Application page.

You should now be logged in to the application.

Step 4. Provide users with your login URL

You can make things easy for your users by providing them with a link to the "User access URL" which automatically logs them in. You can find the URL from the properties tab of your Enterprise Application.