Provisioning Puzzel ID users and groups with Entra ID (Users enablement 1/2)
With the introduction of Puzzel ID, automated synchronization of users and groups with directory systems such as Entra ID is now possible. This synchronization is facilitated by the System for Cross-domain Identity Management (SCIM) protocol, a standard that effectively manages the entire lifecycle of user identities within organizations.
This documentation specifically addresses the configuration of synchronizing Puzzel with Entra ID, although other directory systems supporting the SCIM standard are also supported. For further information about available options, please contact Puzzel support or your customer representative.
This guide will explain how to configure the synchronization of users and groups between Entra ID and Puzzel. The next logical step in the process is to automate access to Puzzel products using the Puzzel ID rule engine. The rule engine has been introduced to address the limited flexibility of Entra ID concerning product access control, enabling more precise management of which users should have access to specific Puzzel products. The steps you need to take with the rule engine after first synchronising your Entra ID users, are described in this article: Configuring product access with Puzzel ID Rule Engine (Users enablement 2/2)
Configuring synchronization of users / groups with Entra ID
Microsoft has tested and approved Puzzel’s SCIM implementation, allowing synchronization and provisioning to be configured through an Entra ID gallery application. The following steps describe how to locate and configure this application for user and group provisioning.
Prerequisites for this section
A Entra ID user with one of the following roles relating to the Puzzel Entra Gallery application:
Application Administrator, Cloud Application Administrator, or Application Owner.A Puzzel ID user account with Admin or Partner role. It is highly recommended that this is a Puzzel ID account created with a system user, not a personal user. Note however that the system user needs to be able to receive the verification email.
Adding the Puzzel application from the Microsoft Entra application gallery
Add Puzzel from the Microsoft Entra application gallery to start managing provisioning to Puzzel.
From the Entra ID main page, navigate to “Enterprise Applications”
Click “New Application”
On the next page “Browse Microsoft Entra Gallery, search for “Puzzel”
You should see a result similar to the screenshot below:
Click on the search result to install the application. If you have previously setup Puzzel for SSO, you can use the same application. However it's recommended that you create a separate app when testing out the integration initially. If you haven’t installed it before, click “Sign up for Puzzel” to continue.
When clicking “Sign up for Puzzel”, you are taken to the screen shown below. Click “Start Onboarding” to start the process.
If you are not already signed in with a Puzzel ID account you will be taken to the Puzzel ID login screen to sign-in. As mentioned above, you will need a Puzzel ID user with the “admin” role to proceed.
Next, verify that the customer name (shown right above the “Onboard SSO” button) is correct, click this button to continue the process.
Once accepted, the applications' service principle is now provisioned into the tenant and you should see the “onboarding completed” page:
The application should now be installed and we can continue to set up the automated user provisioning.
Define who will be in scope for provisioning
The Microsoft Entra provisioning service allows you to scope who will be provisioned based on assignment to the application and or based on attributes of the user.
If you choose to scope who will be provisioned to your app based on assignment, you can use the following steps to assign users to the application. If you choose to scope who will be provisioned based solely on attributes of the user, you can use a scoping filter as described here.
Start small. Test with a small set of users before rolling out to everyone. When scope for provisioning is set to assigned users, you can control this by assigning one or two users to the app. When scope is set to all users, you can specify an attribute based scoping filter.
If you need more roles, you can update the application manifest to add new roles.
Activate automatic user provisioning to Puzzel
This section guides you through the steps to configure the Microsoft Entra provisioning service to create, update, and disable users in Puzzel ID based on user assignments in Microsoft Entra ID.
Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
Browse to Identity > Applications > Enterprise applications
In the applications list, select Puzzel.
Select the Provisioning tab.
Set the Provisioning Mode to Automatic.
In the Admin Credentials section, enter the Tenant Url. This URL will be on the format
https://app.puzzel.com/id/provisioning/<customerId>/scimIf you are unsure what customerId to use here, please reach out to Puzzel Support or other technical contact in Puzzel.
Click on Authorize. In the popup window, make sure that you sign-in with a user that has either admin or partner role assigned:
Click Test Connection to ensure Microsoft Entra ID can connect to Puzzel. If the connection fails, ensure that the customerid as part of the URL above is correct and that your Puzzel account has “Admin” or “Partner” role and try again.
In the Notification Email field, enter the email address of a person who should receive the provisioning error notifications and select the Send an email notification when a failure occurs check box.
Select Save.
Configure mappings between Entra ID and Puzzel
- Under the Mappings section, select Synchronize Microsoft Entra users to Puzzel.
Review the user attributes that are synchronized from Microsoft Entra ID to Puzzel in the Attribute-Mapping section. The attributes selected as Matching properties are used to match the user accounts in Puzzel for update operations. If you choose to change the matching target attribute, you need to ensure that the Puzzel API supports filtering users based on that attribute. Select the Save button to commit any changes.
Note that there is a “retry sync” option available in Puzzel ID under Organisation Settings → User Management (the setting Enable auto provisioning users must be active for these to appear). This requires a mapping to the Puzzel ID field “nickname” from some unused field in Entra ID to work.- Under the Mappings section, select Synchronize Microsoft Entra groups to Puzzel.
Review the group attributes that are synchronized from Microsoft Entra ID to Puzzel in the Attribute-Mapping section. The attributes selected as Matching properties are used to match the groups in Puzzel for update operations. Select the Save button to commit any changes.
Testing the provisioning service
Before enabling the provisioning service it is recommended to do a few tests with select users or groups. This can be done using the “Provision on demand” feature.
Still in the “Provisioning” section of the Puzzel ID application, navigate to “Provision on demand”:
In the field “Select a user or group” enter the name or email address for the user or group you wish to test the synchronization feature with.
Click “Provision” - You should now see a page showing if the provisioning operation was successful or not. If any error occured, there are error messages indicating the root cause.
Enabling the provisioning service
When the testing using the “Provision on demand” has been completed, the provisioning services can be enabled to start the recurring syncrhonization of users / groups between Entra ID and Puzzel.
- To enable the Microsoft Entra provisioning service for Puzzel, change the Provisioning Status to On in the Settings section.
- Define the users that you would like to provision to Puzzel by choosing the desired values in Scope in the Settings section.
- When you are ready to provision, click Save
Assigning users and groups to the Puzzel ID application
Typically you don’t want all the users / groups in your Entra ID directory to have access to Puzzel. To control which users / groups get access, navigate to the “Users and groups” section of the Puzzel ID.
From here you can search for specific users and groups that will be applicable for the user / group provisioning.
A role must be asssigned to a selected user or group. In most cases it is recommended to just use the role “User” in this step. The rule engine will offer options to do more advanced provisioning of roles at a later stage in the process.
The available roles are:
Role | Description |
|---|---|
User | Regular user, such as PCC, PCM, WFM, SI agent or admin |
Admin | Customer administrator - has access to Organisation Settings and can authenticate applications such as Entra ID SSO or provisioning. |
Partner | Partner user, only used for Puzzel partners to give access similar to admin, but includes possibility any registered partner customers |
Troubleshooting
There are two tools that are very useful with regards to troubleshooting the synchronization between Entra ID and Puzzel:
Once you have covered the steps above and provisioned all your users from Entra ID to Puzzel ID, you should continue with assigning them access to products. The steps to do that via the rule engine are described in this article: Configuring product access with Puzzel ID Rule Engine (Users enablement 2/2)