Configuring Single Sign-On with Entra ID (previously Azure AD)
This article describes how to configure single sign-on (SSO) to Puzzel using an external identity provider such as Entra ID (previously Azure AD), ADFS or Google Workspace.
Before you begin
There are a few things that need to be verified before starting the process of single sign-on configuration.
Access to Organisation Settings portal
To configure SSO, you must specify information about your Identity Provider using the “Single Sign-On” section in the Organisation Settings portal. All users with the role of “admin” or “sysadmin” should be able to see the “Organisation Settings” menu option from the Puzzel top bar:
If you don’t see this menu option, and you are a customer administrator, please contact your company’s Puzzel solution owner which should be able to give your user the needed access role. Alternatively reach out to Puzzel support if you are unable to resolve the access issues locally.
Access to your Identity Provider
You must have an existing OIDC or SAML identity provider (IdP) such as Azure AD or Google Workspace. Work with your IdP administrator to gather the necessary information depending on your Identity Provider.
As mentioned above, you also need a user with access to the Organsation Settings portal.
Configure Single Sign-On with Entra ID (previously Azure AD)
This section describes how to configure Single Sign-On by installing the Puzzel app from the Entra Gallery. If you prefer a manual setup of SSO, the steps for doing that is described in a separate chapter below.
Step 1 - Find and add Puzzel application from Entra Gallery
For this step you need access to your company’s Microsoft Entra ID (previously Azure Active Directory) in the Azure portal including access to give administrative consent for the Azure tenant. If you are not an IT administrator for your company you would typically need help from one in order to complete this step.
See https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/what-is-application-management for more details on managing Entra ID apps.
To configure the integration of Puzzel into Entra ID for Single Sign-On, you need to add Puzzel from the gallery to your list of managed SaaS apps.
Log on to Entra ID portal and in the left side menu, select “Enterprise applications”.
On the next screen, click “New application”:
In the search bar, search for “Puzzel” and you should find this app from Puzzel AS:
Click on the search result and you should see a screen on the right where you can choose to “Sign up for Puzzel”:
Step 2 - Onboarding SSO identity
When clicking “Sign up for Puzzel”, you are taken to the screen shown below. Click “Start Onboarding” to start the process.
Next, verify that the customer name is correct (this is shown) right above the “Onboard SSO” button, click this button to continue the process.
Next you will be asked to sign-in and grant consent with an Entra iD (previously Azure AD) administrator account from the Azure tenant you want to onboard.
Once accepted, the applications' service principle is now provisioned into the tenant and you should see the “onboarding completed” page:
Step 3 - Managing an onboarded identity provider
After initial configuration, a connection can be disabled / enabled in the Organisation Settings portal. Choose the “Configure” option in the Single Sign-On option.
Next you should find the configured connection looking similar to the below screenshot, from this view, choose the “edit” icon.
From the next screen it is possible to disable / enable the SSO connection.
Step 4 - Configure externalid for your users that are to use the SSO configuration
The provider configuration behind the Puzzel Entra ID application uses the oid claim as external id claim to map the user to Puzzel ID.
This means that each user that is to use the configured SSO connection will need their respective Entra ID objectid added to their externalid field. See the chapter “Validate users using external id” here.