Microsoft Entra ID Provisioning in Happeo

This article aims to provide you with a guide on how to enable Microsoft Entra ID Provisioning for Happeo.

Package information: Microsoft Entra ID provisioning is available to all packages.

To learn how to set up the Microsoft integrations inside Happeo, please see this article.

In short

To enable Entra ID Provisioning of users and groups:

• You will need an Entra ID enterprise application, which must be created in your Active Directory
• You need to be an administrator of your organization in Happeo to get provisioning credentials

Create a Happeo enterprise application in Etra ID

1. Go to your Microsoft Etra ID Portal
2. Select Etra ID Active Directory
3. Under Etra ID Active Directory, navigate to Enterprise applications
4. Then, under the All applications tab, click New application

You will be taken to Browse Etra ID Gallery. From there:

1. Select Create your own application
2.  Input the name of your app (for example “Happeo Sync”)
3. Select Integrate any other application you don't find in the gallery
4. Then click the Create button

Once the application is created, you will be taken to the Overview.

Obtaining the provisioning credentials from Happeo

1. Log in with your account to beta.happeo.com
2. Go to Admin Settings in the top right corner
3. Select Integrations and click the Setup button for Etra ID Provisioning
   1. Note: A modal will pop up asking for your Etra ID tenant ID if we cannot find it
4. A modal will pop up containing two fields: tenant URL and tenant secret. These will need to be copied to the Etra ID side into the enterprise application

Enable provisioning for the application

This section has been referenced from this link.

Admin credentials

In the Happeo enterprise application (that you have created), go to the tab Provisioning and click the Get started button

Then, you can:

1. Set Provisioning Mode to Automatic
2. Fill in the Tenant URL and Secret Token that you obtained previously from Happeo
3. Click the Test Connection button to verify your Tenant URL and Secret Token
4. You should receive a success notification. Then click the Save button to save the configuration

Troubleshooting

If the testing is not successful, please retrace your steps. If testing continues to not succeed, please contact our support team.

Update Etra ID security token

On August 24th, 2023 we released an improvement to our security token, further increasing security between Happeo’s connection to Etra ID. 

Please note that if you do not follow these 5 steps before then, your integration with Etra ID will stop working. As a result, new users will no longer be provisioned into Happeo, and new fields will not be synced, but you will still have access to the platform.

1. Go Happeo’s Admin panel by clicking on your avatar and then Admin Settings
2. Click on the Integrations section and look for the toggle slider that says Etra ID
3. Slide the toggle off, wait a minute, then slide it on again. A new security token will appear
4. Copy and paste this security token into Etra ID's admin settings
   1. For a more detailed overview, please see the section above starting with "Obtaining the provisioning credentials from Happeo" – it’s the same as when you initially set up Happeo
5. Press the Test button to test the connection
6. If everything works, save it, and you’re done

In the unlikely event that the test fails, please cancel and continue to use the old token and contact our support team.

Mappings

Users

One attribute mapping must be changed for users to provision correctly.

1. In the Edit provisioning tab, click on Mappings and then click on Provision Entra ID Active Directory Users
2. On this page, we need to change the existing mapping for mailNickame to objectID. To do that, click on the row showing that mapping to edit it, and change the source attribute to objectID in the “edit attribute” side-panel. Verify that the target attribute is still externalID
3. Click “Ok” and verify that the mapping is now configured as objectID mapped to externalID. See screenshot below

If the original mapping does not exist for some reason, then you should create a new one, which maps the source attribute objectId to the target externalId.

Groups

Two attribute mappings must be created and added in case groups are used in Etra ID.

1. In the Provisioning Mapping section, click Provision Etra ID Active Directory Groups
2. Check the box Show advanced options and click Edit attribute list for customappsso

Then, create the following two attributes:

Name	Type
urn:ietf:params:scim:schemas:extension:happeo:2.0:Group:emailEnabled	Boolean
urn:ietf:params:scim:schemas:extension:happeo:2.0:Group:email	String

 

You can then:

1. Click the Save button. You will be taken back to the Attribute Mapping screen for Groups
2. You will need to add two new mappings corresponding to these two newly created attributes:
   1. Click Add new mapping and set the source attribute to be mailEnabled
   2. And the target attribute to be the newly created attribute urn:ietf:params:scim:schemas:extension:happeo:2.0:Group:emailEnabled
3. Click Ok
4. Repeat this, setting the source attribute this time to be mail and the target attribute urn:ietf:params:scim:schemas:extension:happeo:2.0:Group:email
5. After you have added these two mappings, don’t forget to save the changes. The screenshot below shows what you should end up with as mappings

Specify users and groups to provision

This is done by first allowing the enterprise application to sync all users and groups, then adding scoping filters.

Sync all users and groups

1. In the Provisioning Settings section, choose Sync all users and groups for scope
2. Click the Save button to save the changes

Note: External users invited to Etra ID cannot log in to Happeo even if they are provisioned successfully. These users must be invited from the Happeo Admin Settings page.

Scoping filters

This section has been referenced from this link.

1. In the Provisioning Mappings section, click Provision Etra ID Active Directory Groups or Provision Etra ID Active Directory Users to manage scoping filters on groups or users
2. You will be taken to the Attribute Mapping view. Click Source Object Scope

You will be taken to the Source Object Scope view:

1. Click Add scoping filter
2. Specify the Filtering Criteria
3. Provide a Scoping Filter Title
4. Click the Ok button to save the scoping filter

You will see the new scoping filter in Source Object Scope and you can continue adding more scoping filters.

Start provisioning

1. Go back to the Provisioning menu. You should see the configured provisioning
2. Tap on the Start provisioning button to start the automatic provisioning from Etra ID to Happeo 

Setting up user and sync group

Once you've followed all the steps in this article, you should see two applications for Happeo in the Etra ID > Enterprise Applications list:

1. One that you have created (named something like Happeo sync and the icon will be the first letter on a colored background)
2. And one called Happeo, which has the Happeo logo as the icon

Considerations for user and group sync

There are two options for selecting users and groups to provision and sync:

1. Assigning users and groups to the application
2. Or syncing all users

How these work are described in the accordions below, including recommendations on when and how to use each case.

Key considerations for syncing groups, which apply to both options:

• Permissions to create Pages and Channels are based on Groups
• By default, the permission is set to True, so all members of all Groups have permission to create Pages and Channels
• If a user belongs to even one group that has permission to create Pages and Channels, they will have that permission
• Our recommendation is that not everyone should have permission to create Pages and Channels, so these would need to be unchecked. Currently, it is a manual process that needs to be done individually for each group, so we recommend not syncing (all) groups until it has been well defined which ones are necessary
• Group's member count in Happeo will only show users that have been synced. So if a group in Etra ID has 50 members, but only 40 of them are considered users of Happeo, the member count in Happeo will show as 40

Group types in Microsoft

• Security groups
  • Security groups are usually used more for assigning permissions or access
  • Security groups do not have an email address within Microsoft, but when a security group is synced to Happeo, an email address is generated within Happeo for it
• Microsoft 365 groups
  • Each Etra ID Active Directory auto-creates a Microsoft 365 group that contains all users in the environment and is also visible to everyone in Teams. Out of these options (when creating a new Teams group), it's an org-wide group
    • Microsoft 365 groups have an email address

• Teams groups
  • When creating a new team, it's possible to create it from an existing Microsoft 365 group or create an entirely new group
  • Creating a Team automatically creates a Microsoft 365 group, but you can create Microsoft 365 groups without creating a Team
  • There isn't a way to determine in Etra ID if a Microsoft 365 group has a Team linked to it, or whether it's private or open to join
  • For Teams that are public (anyone in your org can join), note that anyone who joins that group is able to gain access to content shared with that group (within Happeo)

Troubleshooting

Why can’t I log in to Happeo?

If you encounter login issues with Happeo, specifically Etra ID provisioning failures resulting in denied access, it might be due to the Etra ID security token not being updated as outlined in the "Update Etra ID security token" section above. 

As an administrator, it is crucial that you adhere to the security token updating steps to guarantee that both you and the users within your environment can successfully access Happeo.