This article provides a comprehensive guide on how to integrate CybSafe with Microsoft Entra ID for automated user provisioning.
By configuring this integration, Microsoft Entra ID can automatically provision and de-provision users and groups to CybSafe using its provisioning service, streamlining identity management and ensuring your CybSafe user base is always up-to-date.
For important details on what this service does, how it works, and frequently asked questions, see Automate user provisioning and deprovisioning to SaaS applications with Microsoft Entra.
⚠️ When automatic user provisioning is active, all user management should be performed in Microsoft Entra.
Any changes made within the CybSafe platform can be reverted when your provisioning sync next runs.
Capabilities supported
Create Users: Users created in Microsoft Entra ID can be automatically provisioned to CybSafe.
Any deactivated users will be reactivated.
Update User Profiles: Changes to user attributes (e.g., display name, email address) in Microsoft Entra ID are automatically synchronised to CybSafe.
Deactivate Users: When a user is disabled or removed from the sync'd group in Microsoft Entra ID, their account in CybSafe will be automatically deactivated.
Provision Groups: Group memberships can be synchronised and used to control your CybSafe user base.
Prerequisites
Before you begin, ensure you have the following:
Microsoft Entra ID Premium P1 or P2 license: SCIM provisioning capabilities require a premium Entra ID license.
Administrator access to Microsoft Entra ID: You'll need permissions to add and configure enterprise applications.
Administrator access to CybSafe: You'll need access to CybSafe's settings to obtain the necessary SCIM token.
Planning your provisioning deployment
Consider the following points as part of your deployment plan:
Learn about how the provisioning service works.
What is your provisioning scope? Determine which users and groups you want to provision to CybSafe. Will it be all users, specific groups, or only users or groups assigned to the CybSafe enterprise application?
Usually a specific Entra group is used and the members of this group are assigned to the CybSafe app for provisioning.
You can further restrict the users who are provisioning by using scoping filters against specific attribute mappings.
Attribute Mapping: Understand how user and group attributes in Microsoft Entra ID correspond to attributes in CybSafe. This is crucial for accurate data synchronisation.
Start by thinking about how you want to report on your users and how you'll assign content to them.
By syncing specific user details from Entra to CybSafe attributes Department, Division, and Organisation, you'll automatically create corresponding groups within CybSafe.
You can then use these groups to:
Filter your reports, giving you targeted insights.
Assign content or phishing campaigns to specific sets of users, making your security training more relevant.
Data Consistency: Ensure that the unique identifier for users (e.g.,
userPrincipalName, emailormail) is consistent across both systems to prevent duplicate accounts.Ensure you map the same attribute within your SSO configuration to avoid duplicate users.
Setup
CybSafe Recommends and good to know
Define your reporting or content assignment requirements and map these user profile attributes to our target attributes Department, Division and Organisation. Only these three root folders show in our dashboards and CSV exports.
Create an Entra group to add users to it who require access to CybSafe. Removing users from this group will de-provision them. Do not use an existing group that controls other permissions within your organisation as you may not be able to remove them from the group without impacting other services.
Ensure the addition or removal from the above group is part of your JML process.
Start with a small user set added to your group until you are comfortable that the correct attributes are being used.
If you hit your licence limit your provisioning service will continue to create new users however in a deactivated state on the CybSafe platform. Once you expand your licence limit you will need to manually activate these profiles on CybSafe.
Step 1. Add CybSafe from the Entra application gallery
Add CybSafe from the Entra application gallery to start managing provisioning to CybSafe.
Click ➕ New Application.
Search for CybSafe and install the App.
If you have previously setup your SSO integration with CybSafe using Entra our App will already be installed. Simply search for our app in your list of installed apps.
Learn more about adding an application from the gallery here.
Step 2. Configure the CybSafe Enterprise application for provisioning.
Add the admin credentials
Navigate to the Provisioning tab;
Click get started and set the Provisioning mode to "Automatic".
Add our Tenant URL for CybSafe is:
https://app.cybsafe.com/scim/v2/.Ensure you maintain the trailing slash for our URL.
Generate a provisioning token from our User provisioning tab under the Identity management menu.
Add the token to the Secret token field in the app.
NB! this token can only be used with one CybSafe Entra App.
Final Step here is to click on Test connection to ensure you have not made a mistake adding the credentials.
If you encounter an error;
Ensure your CybSafe account has Admin permissions and try again.
Ensure you have not added a space before or after the Tenant URL.
Ensure that you have not incorrectly copied the SCIM token from the CybSafe platform.
Configure your attribute mappings
Navigate to the Mappings section of the Provisioning App.
Click on "Provision Microsoft Entra ID Users"
Set the attributes to ensure you provide the relevant information to CybSafe.
User attributes will populate their CybSafe profile and enrich your group management and reporting capabilities.
For a list of supported attributes see our Supported SCIM Attributes section.
Configure your Settings
Under the settings select Sync only assigned users and groups.
You can also choose to;
Send a notification to an internal team when a failure occurs
Prevent accidental deletion
Assign your user group to the CybSafe App
Navigate to the Users and groups menu within the App and add the group you created to provision users to CybSafe.
When adding the group or an individual user ensure the "Role" is set to "User", this is the only role we can accept.
We currently do not support setting user permissions from an automated provisioning sync. The users permissions for CybSafe can only be set from within the CybSafe platform.
As part of your initial deployment we recommend limiting the membership of this group to ensure you are happy with your configuration.
When you are ready to deploy to your entire organisation you can simply add the users as members to the group at this point.
If you do not wish to use a group but rather Scoping filters, see this section Using scoping filters on the tweaks to the setup.
Turn on your Provisioning sync.
Navigate back to the Provisioning menu and change provisioning Status to on.
This will start your provisioning sync, only action this step once you are happy with your configuration.
The initial synchronization cycle takes longer to perform than subsequent cycles, which occur approximately every 40 minutes as long as the Entra provisioning service is running.
Monitor your deployment
Once you've configured provisioning, use the following resources to monitor your deployment:
Use the provisioning logs to determine which users have been provisioned successfully or unsuccessfully
Check the progress bar to see the status of the provisioning cycle and how close it is to completion
If the provisioning configuration seems to be in an unhealthy state, the application will go into quarantine. Learn more about quarantine states here.
Go to The Identity Management section in the CybSafe Platform, view the SCIM Token Section where you can observe the "Last SCIM Request" and "Last SCIM Change" date and time.
Note: You can assign someone via Entra who is already in the CybSafe platform, If the email addresses are identical we will sync the profiles.
If the email addresses do not match, a second identity will be created.
Supported SCIM attributes
* The column titled, M, O or R stands for Mandatory, optional or recommended fields. Some mandatory fields such as language are recommended but they cannot be deleted from the mapping.
** These attributes may need to be added to the schema via Azure, read more here.
The attribute names below are the camelcase field names and can be used as the target attribute, unless otherwise stated in additional information.
CybSafe will only show data in a field if it exists in your Entra, any fields mapped with no user data will still show as blank.
CybSafe attribute name | Description | Additional information | *M, O or R |
userName | Required by SCIM, usually primary work email address. | Often maps to userPrincipalName | M |
active | Deactivate or activate a user. | Active users in Entra are provisioned as active in CybSafe. Deactivated users in the assigned group are provisioned but deactivated. | M |
emails[type eq "work"].value | Work email address marked as primary. |
| M |
givenName | Users first name. |
| R |
familyName | Users surname. |
| R |
preferredLanguage | Language tag used for email communications, as defined per RFC 5646: | A full list of supported languages and the associated code can be found here | M |
timezone | Add users timezone via an expression, we recommend using the IANA timezone format. i.e. Europe/London. | More information on how to setup a timezone expression. | R |
** manager | Sync users line manager info. The line manager will need to exist in CybSafe to link the profiles. | Target attribute will need to be created in Azure, using the following string as the target:
| R |
department | Sync user department information to the folder in group management. | Shown as a string in the target attribute list. Useful for filtering in campaigns and reporting | R |
organization | Sync any other user information to the organization folder in group management. | Shown as a string in the target attribute list. Useful for filtering in campaigns and reporting | R |
division | Sync any other user information to the division folder in group management. | Shown as a string in the target attribute list. Useful for filtering in campaigns and reporting | R |
** addresses[type eq "work"].country | Users country location such as GB, US, RSA, FR. | May need to be added via the Azure portal, use the standard field name as shown. | R |
** externalId | Sync any relevant external id's to CybSafe that you hold. | CybSafe recommend you share your users Object ID to this field to ensure the Teams integration is as robust as possible. | O |
** office | Sync users office location details. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** streetAddress | Sync aspects of a users address. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** city | Sync a users town or city location. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** state | Sync state, county or province. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
title | Sync users job titles to the platform. |
| O |
** businessUnit | Sync additional user details about their business unit or other departmental structures. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** employeeNumber | Sync users employee numbers/id's. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** costCenter | Sync users cost centre details. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** employeeType | Sync users employee type such as permanent, contractor or part time. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** employeeLevel | Sync users employee level or other defining criteria. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** grade | Sync a user's grade or other defining criteria. | Target attribute will need to be created in Azure, using the following string as the target:
| O |
** hireDate | Sync users hire or start date. | Target attribute will need to be created in Azure, using the following string as the target:
Use an expression, change the source to match you information: FormatDateTime([employeeHireDate], , "yyyy-MM-ddTHH:mm:ssZ", "yyyy-MM-dd") |
|
Other available attribute
The following attributes are available within the Enterprise app or to be added to the schema but are currently not used within the CybSafe platform.
CybSafe attribute name | Description | Additional information | *M, O or R |
id | Do not use this target attribute, it cannot be used and will cause an error in your mapping. |
| N/A |
userType | Currently not used but may be used to sync user permissions. |
| N/A |
displayName | Sync a display name. | Does not show in the platform or any reports, may be available via the CybSafe API. | N/A |
nickname | Sync a nickname. | Does not show in the platform or any reports, may be available via the CybSafe API. | N/A |
formalName | Sync a formal name. | Does not show in the platform or any reports, may be available via the CybSafe API. | N/A |
middleName | Sync a middle name. | Does not show in the platform or any reports, may be available via the CybSafe API. | N/A |
honorificPrefix | Sync a user's honorific prefix. | Does not show in the platform or any reports, may be available via the CybSafe API. | N/A |
honorificSuffix | Sync a user's honorific suffix. | Does not show in the platform or any reports, may be available via the CybSafe API. | N/A |
phone | Sync a user phone number | Does not show in the platform or any reports, may be available via the CybSafe API. | N/A |
locale | Sync a users locale. Currently not used to impact the CybSafe platform. | Does not show in the platform or any reports, may be available via the CybSafe API. | N/A |
We have three root folders in CybSafe group management to map attributes to, these are called Department, Division and Organization.
These fields can be used to assign content and phishing to users and are available in your reporting to break down your users into groups.
Departments - Most customer point this to a department attribute that indicates, Sales, Finance, HR, Customer Service etc.
Division and Organisation - can be mapped to any other useful fields you have such as a higher level group/department structure such "Office of the CFO" as an example.
Please note: any other attributes from your SCIM will not sync across. Only the above attributes will be captured by CybSafe if mapped.
If you have attribute mappings that you wish to be synced across to Group management please ensure they are under Department, Division or Organisation.
Additional note- For organisations where the userPrincipalName differs to the full email address please contact CybSafe customer support and confirm your preferred user property which contains the full email address.
If you have a mismatch between the full email address and userPrincipalName, users may experience login issues or create duplicate profiles on CybSafe.
Timezone expression mapping
Entra does not have a native Timezone user field.
To add timezones to your sync you will need to configure an expression using another accurate user attribute to provide the timezones in IANA format.
The expression is as follows within the attribute mapping.
Switch(ToLower([source]), "defaultValue", "key1", "value1", "key2", "value2", …)
ToLower - converts the source to lower case as entra is case sensitive.
Source - points to the property that you are using within Entra to find the key.
Default value - is a fall back if the user does not have any information.
Key - is your lookup that will give the user their timezone, such as a country or city location.
Value - is the timezone you want to sync to CybSafe.
The expressions could look like this using country as a source:
Switch(ToLower([country]), "Europe/London", "united kingdom", "Europe/London", "germany", "Europe/Berlin", "south africa", "Africa/Johannesburg", "zimbabwe", "Africa/Harare", "spain", "Europe/Madrid", "es", "Europe/Madrid", "france", "Europe/Paris", "iceland", "Atlantic/Reykjavik", "namibia", "Africa/Windhoek", "nigeria", "Africa/Lagos")
⚠️
Take note of potentially using Alpha 2 codes for the country in the Spain example. "spain" vs "es".
The Keys will need to be accurate to an exact match to what is in the user properties.
The above is looking for country and then mapping a timezone for the user. Of course we could use anything as the source as long as the field is accurate for ALL users.
Using a City field might be the better option where a country could have multiple time zones to be more accurate. Maybe you have accurate office locations in Entra to use too.
Within Entra it would look as follows.
Use Scoping filters instead of an entra group
If you do not wish to use an Entra group, you can use Scoping filters on our Attributes to sync through the relevant users. To Do so you will need to make the following tweaks to your setup.
⚠️ This setup will sync all Entra accounts to your CybSafe account, including all service accounts, meeting rooms and printers etc. Only use this method if you are certain on your scoping filters to only sync active legitimate users to CybSafe.
Under Settings set your Scope to sync all users and groups.
Navigate to the Mappings, select, "Provision Microsoft Entra ID Users"
Under Source Object Scope, select "All records".
Within this menu, click on "Add new filter group", you will need to build the relevant filters against each appropriate attribute to ensure the correct users are within scope of provisioning.
Build out the filters accordingly to sync the correct users.
How to add additional attributes to the CybSafe Gallery app schema
Cybsafe's Entra gallery app may not support the adding of custom target attributes for some customers. You may need to add additional attributes for a variety purposes so it is necessary to follow the below steps to ensure you can add them.
Contact our support team to ensure the target attribute is available and supported. This user data will not show in Group management or our CSV's and will only be available via our API bolt on.
Click the following link and login with your Microsoft administrator account: https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true . This will force the ability for you to edit schemas in Microsoft Entra.
Navigate to your Microsoft Entra environment and the Enterprise applications page. Click on CybSafe. From here, select "Provisioning" on the left hand menu.
Click on "Edit provisioning".
Select Microsoft Entra ID Users.
Open the advanced options.
Click on Edit attribute list for CybSafe.
Enter in the target attribute from CybSafe. If you are unsure of what attribute to enter contact your customer success manager or [email protected]. Save it as a string, and click save.
Go back to the Attribute Mapping page. Click on Add New Mapping.
Select the target attribute you entered earlier. Then select what source attribute you would like to map it to. Then hit save.
You should see the new mapping in the attribute mapping page
Still have any questions?
If you have any questions or concerns, you can contact the team at [email protected] and we’ll be happy to answer them.