Configuring SSO and directory syncing with Entra and Lookout

This guide explains how to connect Lookout to Microsoft Entra, so your team can log in with their Microsoft account and have their user details automatically kept in sync. It covers what you need before you start, how to set up single sign-on (SSO) and directory syncing in both Entra and Lookout, how to create Staffers and Helpers automatically from Entra groups, and what to do if something isn't working.

Before you start

Directory syncing is required for SSO to work. Users must be synced into Lookout with the correct IDs so they can be recognised when they log in.

If you would like SSO turned on, contact your customer representative, who will discuss billing with you. After that, the process is entirely self-serve.

Before you start, you will need:

The "SSO/SCIM integration" RBAC permission. If you are using the old Lookout permissions, you will need both the "Login management" and "Technical" permissions.
Permission to administer Enterprise applications in your organisation's Entra instance.

If you already have users in Lookout and are adding SSO, please see our FAQ below - How to prepare your Lookout instance for SSO.

Entra: Create a new Enterprise Application

Create a new enterprise application in your organisation's Entra.

Create your own application and call it “Lookout”.

Click on Single Sign On and choose SAML.

Important step: Copy the App Federation Metadata URL in the SAML certificate section.

Lookout: Configure SSO integration

From your home dashboard, navigate to the overflow menu by clicking the ellipsis (...) next to your name in the bottom left-hand corner.
The overflow menu will open - click Settings.
In the main settings, navigate to the Technical section, then click Single sign-on.
Click on Edit configuration.

Set Identity provider name to the name of your IdP, e.g. Microsoft or Google.
Set Identity provider SAML metadata URL to the Metadata URL you copied earlier.
Then, click Save.

Important: Check these details before continuing. Once the SSO infrastructure has been built, the identity provider name and metadata URL can't be changed.

Click on the Build SSO infrastructure and wait for it to complete.

Once provisioning is complete, you will be given:
1. Identifier (SAML audience)
2. Reply URL (SAML assertion URL)
3. Two certificates to download: the SAML verification certificate and the SAML token encryption certificate
4. A URL (Tenant URL) for directory syncing

Click Regenerate secret to create your directory syncing secret (bearer token).

Important: You must copy this directory syncing secret now, as it won't be shown again.

Entra: Complete application configuration

Within the Basic SAML Configuration section, click Edit.
Add the Identifier and Reply URL provided by Lookout.

In the Attributes & Claims section, remove all attributes except Unique User Identifier.
Click on Add new claim.

Set Name: idp_user_id attribute and map it to Source Attribute: user.objectid.

You should have two claims:
1. Required claim: Unique User Identifier (Name ID).
2. Additional claim: idp_user_id.

Configure Entra to verify SAML requests from Lookout

Within the SAML Certificate section, click on Edit next to Verification certificates.

Enable Require verification certificates.
Upload the SAML verification certificate downloaded from Lookout.

Configure Entra to sign tokens issued for Lookout

Navigate to Token encryption.
Import the SAML token encryption certificate downloaded from Lookout.
Activate the certificate.

Navigate back to the Single sign-on page.
Within the SAML Certificates section, click Edit.
Change the Signing Option to Sign SAML response and assertion.

Configure Provisioning

For SSO to work, users must be "provisioned" (synced) from the IdP (Entra) to Lookout. Below are instructions for both the current and previous Microsoft Entra interfaces.

Enable Provisioning (new user experience instructions)

Please note: These instructions follow the current Microsoft Entra interface.

To enable provisioning in the Enterprise Application:

Click on Get Started under 3. Provision User Accounts.

Click on Connect your application under Create configuration.

Make sure the authentication method is set to Bearer authentication.
Add the Tenant URL and Secret token provided by Lookout.
Click Test connection and make sure it works.
Click Create.

Enable Provisioning (legacy user experience instructions)

Please note: These instructions follow the previous Microsoft Entra interface.

Use automatic provisioning mode, and add the Tenant URL and secret token provided by Lookout.
Test the connection to make sure it works.

Manage Provisioning

Under Manage, click on Provisioning.
Expand the Mappings section and click on Provision Microsoft Entra ID Users.

Make sure the userName attribute maps to the Microsoft Entra ID attribute userPrincipalName.

Important: Lookout uses this value as the user's email address and uses it to find existing users. Each user's User Principal Name in Entra must match their email address in Lookout.

Configure the provisioning user mapping so that externalId points to objectId.

Assign users

Users or groups must be "assigned" to the application before they will be provisioned.

Lookout can automatically create Staffer and/or Helper records for your users. Without this, you must create Staffer and/or Helper records manually.

We recommend creating a "Lookout Staffers" group, and optionally a "Lookout Helpers" group, in Entra. Assign users to these groups based on the user type(s) they need in Lookout. The groups will sync to Lookout and appear on the SCIM page under Settings › Technical. This is where you set up the automatic user type rules.

We recommend setting this up before adding your users to the groups, so their roles are in place from the first sync.

Top tip: Helpers created this way start in a pending state, so review and complete their details after they sync. Removing someone from a group does not disable or archive their Staffer or Helper record. You will need to offboard them in Lookout.

See our FAQ below on Using simple role creation from SCIM group syncing to learn more.

Once this is set up, return to Microsoft Entra.

Click on Add user/group.

Click Overview and click Start provisioning.

This may take up to an hour to complete. Check for errors if it does not.

Provisioning in Entra should now be automatic. When users are added, removed or deactivated, the changes will appear in Lookout. Check the provisioning overview for details.

Lookout: Enable SSO

Let's head back into Lookout now.
From your home dashboard, navigate to the overflow menu by clicking the ellipsis (...) next to your name in the bottom left-hand corner.
The overflow menu will open - click Settings.
In the main settings, navigate to the Technical section, then click Single sign-on.
Click Enable SSO to turn on SSO sign-in, then confirm. Make sure your first sync in Entra has finished before you do this.

Single Sign On should now work, if the user has been provisioned correctly.

Please be aware it may take up to 24 hours for certificates to be available if you receive errors regarding certificates.

FAQs

How to prepare your Lookout instance for SSO

We recommend checking the email addresses of the users you expect to use SSO against the users already in Lookout. This prevents the problem described in User created with wrong email FAQ below, which can be difficult to fix if someone starts using the wrongly created user.

Lookout matches users on their Entra User Principal Name, so compare each user's User Principal Name as well as their email.
To get a report of users from Entra, go to the group you are going to assign to the application and click Members > Bulk Operations > Download Members.

In Lookout, create a report using the data export category Profiles and export emails. You can also limit it to staffers and/or helpers.

Use a tool like Excel or Google Sheets to find any emails that don't have a match. An example workbook for Excel: Email matching.xlsx
Update any emails that don't match in Lookout.

What properties are synced to Lookout from Entra?

The provisioning process finds users in Lookout by email address and writes Entra's Object ID into their account. This ID is then used during login instead of the email address. This helps prevent account takeovers.
The Entra displayName field is also mapped to the full_name field in Lookout.
Any other fields need to be set up in Lookout separately.

Certificate issues

If you cannot get to the Microsoft login screen after setting up the certificates, the SAML verification certificate is incorrect.

If you cannot return to Lookout after logging in with Microsoft, the SAML token encryption certificate is incorrect.

Groups not syncing

Groups only sync through automatic provisioning. Allow up to an hour for automatic provisioning to run. Group syncing doesn't work well with provisioning on demand.

User created with wrong email

This can happen if a profile is created in Lookout with an email that's different from the one in your IdP. We recommend:

Find the wrongly created user in Lookout using the Profile search.
Go to the profile and press Edit profile.
Scroll to the bottom and permanently delete the profile.
Update the user's email so it matches your IdP.
Manually provision the user from Entra. The user should now be linked correctly, and SSO will work for them.

Login errors

If SSO sign-in fails, Lookout shows one of these messages:

No account was found matching your SSO identity: The user hasn't been provisioned, or was provisioned with a different ID. Check the provisioning logs in Entra and provision the user again.
Your account was found but is not configured for SSO sign-in: SSO is turned off for that user. Turn it back on in the Login management section of their account.
Your SSO provider did not supply a user identifier: The idp_user_id claim is missing or mapped incorrectly. Check Attributes & Claims in Entra.
In the mobile app, all three show as "User not found".

Profile created without email

This can happen if the work email field isn't filled in in your IdP. Without a work email, SSO provisioning creates a profile in Lookout without a User record.

From the main navigation menu, click Profile search. If all sections are expanded, you may need to scroll to find it.
You'll see all the profiles currently in Lookout.
You can search existing profiles by:
- Name - first name, last name, or preferred name
- Email address
- Telephone number
- Unique ID (UUID)
You can also filter by role to narrow the list. Each result shows the person's full name, email address, and roles.
Click on a name to open their profile.
Click on Edit profile button in the top right-hand corner.
Scroll to the bottom and permanently delete the profile.
In your IdP, set the user's work email.
Manually provision the user. The user should now be linked correctly, and SSO will work for them.

Firing actions from SCIM events

There are two ways to react to SCIM events:

Use the built-in Helper and Staffer creation based on SCIM groups.
- Good for setups without many rules and with simple onboarding of staffers and helpers.
- See Using simple role creation from SCIM group syncing FAQ below for instructions.
Use webhooks and the Workato integration.
- Better for complex onboarding, e.g. creating a ticket and assigning people to complete onboarding steps.

Using simple role creation from SCIM group syncing

From your home dashboard, navigate to the overflow menu by clicking the ellipsis (...) next to your name in the bottom left-hand corner.
The overflow menu will open - click Settings.
In the main settings, navigate to the Technical section, then click SCIM.
This shows the groups already synced from Entra. If you don't see the groups you expect, make sure:
- Group syncing is enabled in your integration.
- The group has been added to the Lookout Entra application.
- Provisioning has been set to automatic. See our section above, Start provisioning for more information. Group syncing can have problems if you provision the group manually, and usually, only automatic provisioning syncs groups properly. You may have to wait up to 24 hours for the next automatic provisioning.
Once the group appears, choose which roles you want created for users in that group.
To backfill existing users, use the Compare button to see roles that are missing or that should be removed. Use the Apply settings button to create the missing roles. Roles are never removed based on group settings. They will still appear in the Compare table, and you can use the links in the table to remove them if you wish.

The screenshot below shows the SCIM groups page in Lookout's Settings. The groups will match the groups assigned to the Lookout application in Entra.

Turn off syncing

Disabling SSO does not turn off SCIM syncing. To stop syncing, change the SCIM secret by clicking Regenerate secret. You will need to update the secret in Entra when you are ready to start syncing again.

How does automated staffer provisioning work?

On the first sync, Entra finds existing users in Lookout by email address. Where there's a match, it updates the Lookout user with the Object ID, which is used from then on. Where a user is missing, it creates a new one.

What happens when a user is deleted in Entra?

If a user is disabled or deactivated in Entra, or removed from the group(s), their user account in Lookout will be disabled but not removed.
If a user is deleted in Entra, their User record in Lookout will be removed, but their Profile, Staffer and Helper records will be kept. None of the records they created will be deleted, only the User record.

Can Access Roles be assigned/managed through Entra?

No. Permissions can't be synced from Entra, and access roles can't be synced from any other system or service. They need to be set up manually in Lookout.

Still need help?

If you're still experiencing issues, please contact our Support Team and include:

Screenshots (if possible)
The user's name/email
The type of notification affected
The channel you expected it on (in-app, email, or push)
The exact steps taken