Microsoft Entra ID Integration Troubleshooting Guide
Microsoft Entra ID integration errors typically occur when required synchronization settings are missing, app roles are invalid, brands cannot be found, or configuration limits are exceeded. This article explains common Microsoft Entra ID synchronization errors in BoldDesk and provides steps to resolve them.
Microsoft Entra ID was previously known as Azure Active Directory (Azure AD). Some older error messages, logs, or configuration references may still use the Azure AD name.
Prerequisites
Verify the following:
- The Microsoft Entra ID app is installed in BoldDesk.
- The synchronization type is configured correctly (Agent, Contact, or Both).
- Required Microsoft Entra ID app roles are created and assigned.
- App roles configured in BoldDesk match those in Microsoft Entra ID.
- User provisioning is configured using a valid Tenant URL and Secret Token.
Access the Microsoft Entra ID Configuration
- Navigate to Admin > Marketplace.
- Open Microsoft Entra ID.
- Review the agent and contact synchronization settings.
- Correct any invalid configuration.
- Save your changes.
Quick Resolution Guide
| Error Message | Cause | Resolution |
|---|---|---|
| Validation failed | Invalid configuration exists | Review field-level validation errors |
| Invalid configuration data | Missing or unsupported value | Verify all required settings |
| Agent role required | BoldDesk role not selected | Select a BoldDesk role |
| Ticket access scope required | Scope not selected | Select a ticket access scope |
| Contact role required | App role missing | Select a Microsoft Entra ID app role |
| Role ID required | Role-based synchronization enabled without a role | Select an app role |
| Role ID invalid | App role cannot be validated | Verify the role exists and is assigned |
| App role must be unique | Same role used in multiple configurations | Assign unique app roles |
| Brand ID required | Ticket Brand Access not configured | Select a ticket brand |
| Brand invalid | Brand no longer exists | Select a valid brand |
| Agent configurations exceeds maximum limit | Configuration limit reached | Remove or reuse existing configurations |
General Configuration Errors
Validation Failed
Error Message
Validation failed.
Cause
BoldDesk cannot validate one or more configuration settings.
Resolution
- Review the entire synchronization configuration.
- Look for additional field-level validation messages.
- Correct invalid or missing values.
- Save the configuration again.
If no specific validation error is displayed, contact BoldDesk Support.
Invalid Configuration Data
Error Message
Invalid configuration data.
Cause
One or more configuration values are incomplete, invalid, or unsupported.
Resolution
Verify that:
- A synchronization type is selected.
- Required app roles are configured.
- BoldDesk roles are selected.
- Ticket Access Scope is configured.
- Ticket Brand Access is configured.
Remove incomplete configurations and save again.
Agent Configuration Errors
Agent Configurations Exceed Maximum Limit
Error Message
Agent configurations exceed maximum limit.
Cause
The maximum number of supported agent configurations has been reached.
Resolution
- Review existing agent configurations.
- Update an existing configuration instead of creating a new one.
- Remove configurations that are no longer required.
- Save your changes.
This error is unrelated to your Microsoft Entra ID subscription. It refers only to the number of agent configurations supported by the BoldDesk integration.
Agent Role Required
Error Message
Agent role required.
Cause
A BoldDesk role has not been selected.
Resolution
- Open the affected agent configuration.
- Select a BoldDesk role.
- Review the configured ticket permissions.
- Save the configuration.
Ticket Access Scope Required
Error Message
Ticket access scope required.
Cause
No Ticket Access Scope has been selected.
Resolution
- Open the affected agent configuration.
- Select the required Ticket Access Scope.
- Save the configuration.
Contact Configuration Errors
Contact Role Required
Error Message
Contact role required.
Cause
Role-based contact synchronization is enabled, but no Microsoft Entra ID app role has been configured.
Resolution
- Open the contact configuration.
- Verify Sync only users of a specific role is selected.
- Select the required app role.
- Ensure the same role is assigned to users in Microsoft Entra ID.
- Save the configuration.
If role filtering is not required, synchronize users regardless of role.
Invalid Contact Deletion Type
Error Message
Invalid contact deletion type.
Cause
An unsupported contact deletion setting has been stored in the configuration.
Resolution
- Open the contact synchronization settings.
- Select a valid contact deletion option.
- Save the configuration.
When a synchronized contact is deleted or unassigned in Microsoft Entra ID, the corresponding BoldDesk contact is soft-deleted and moved to Deleted Contacts. Associated tickets are marked as spam.
App Role Errors
App Role Must Be Unique
Error Message
App role must be unique for all agent and contact configuration.
Cause
The same Microsoft Entra ID app role is being used in multiple role-based configurations.
Resolution
- Review all agent and contact configurations.
- Identify configurations using the same app role.
- Assign a unique app role to each configuration.
- Save the changes.
Role ID Required
Error Message
Role ID required.
Cause
Role-based synchronization is enabled but no app role has been selected.
Resolution
- Open the affected configuration.
- Select a valid Microsoft Entra ID app role.
- Save the configuration.
Role ID Invalid
Error Message
Role ID invalid.
Cause
The configured app role does not exist or cannot be validated.
Resolution
- Verify the role exists in Microsoft Entra ID.
- Confirm the role is enabled.
- Ensure the role is assigned to users.
- Verify the role configured in BoldDesk matches Microsoft Entra ID.
- Save the configuration.
- Restart provisioning if role assignments or provisioning scope changed.
If a Microsoft Entra ID app role is renamed, removed, or replaced, update the corresponding configuration in BoldDesk and restart provisioning.
Brand Configuration Errors
Brand ID Required
Error Message
Brand ID required.
Cause
Ticket Brand Access has not been configured.
Resolution
- Open the affected agent configuration.
- Select the required brand or brands.
- Save the configuration.
Brand Invalid
Error Message
Brand invalid.
Cause
The selected brand no longer exists in BoldDesk.
Resolution
- Open the affected configuration.
- Review the selected Ticket Brand Access.
- Select a valid brand.
- Save the configuration.
Users Are Not Synchronizing
If the configuration saves successfully but users are not synchronized, review the Microsoft Entra ID provisioning logs.
Review Provisioning Logs
- Sign in to the Microsoft Entra admin center.
- Open the BoldDesk enterprise application.
- Navigate to Manage > Provisioning.
- Select View provisioning logs.
- Locate the affected user.
- Review any provisioning failures.
- Correct the reported issue.
- Restart provisioning if necessary.
Provisioning changes may not take effect immediately because Microsoft Entra ID runs synchronization on a scheduled interval.
Contact BoldDesk Support
Contact BoldDesk Support if:
- Validation errors continue after corrections are made.
- No field-specific error is displayed.
- Valid app roles are rejected.
- Valid brands are rejected.
- Users still fail to synchronize after reviewing provisioning logs.
Provide the following information:
| Information | Required |
|---|---|
| Organization URL or Organization ID | ✅ |
| Exact error message | ✅ |
| Screenshot of the configuration page | ✅ |
| Synchronization type | ✅ |
| Synchronization scope | ✅ |
| App role name | ✅ |
| Affected BoldDesk role or ticket permissions | ✅ |
| Provisioning log details | ✅ |
| Date, time, and time zone of occurrence | ✅ |
Do not include Secret Tokens, API keys, passwords, cookies, or other authentication credentials in your support request.
Frequently Asked Questions
1. Can the same Microsoft Entra ID app role be reused?
No. Each role-based configuration must use a unique Microsoft Entra ID app role.
2. Are Microsoft Entra ID app roles and BoldDesk roles the same?
No.
- Microsoft Entra ID app roles determine which users are synchronized.
- BoldDesk roles determine the permissions assigned to synchronized agents.
3. What happens when a synchronized agent is deleted?
The corresponding BoldDesk agent is deactivated, and unresolved tickets assigned to that agent are moved to Unassigned.
4. What happens when a synchronized contact is deleted?
The corresponding BoldDesk contact is soft-deleted and moved to Deleted Contacts. Existing tickets are marked as spam.
5. Where can I investigate failed synchronization events?
Open:
Microsoft Entra Admin Center > Enterprise Applications > BoldDesk > Provisioning > View Provisioning Logs
