This step-by-step provides instructions for:
userRole (Admin, ContentManager, Creator, Viewer)
businessRole (IT, HR, etc.)
Prerequisites and Permissions
Before starting the configuration, ensure you have the following in place:
1. Licensing requirements:
Microsoft Entra ID P1 (minimum) or P2 (recommended for advanced features)
Alternatively, EMS E3/E5 subscription covers provisioning capabilities
Group-based provisioning requires Premium edition
2. Required administrator roles:
Application Administrator. Full management of enterprise applications and provisioning configuration.
Cloud Application Administrator. Same capabilities except Application Proxy management
For delegated administration, these granular permissions apply:
For start/stop operations:
microsoft.directory/servicePrincipals/synchronizationJobs/manage
For attribute mappings:
microsoft.directory/servicePrincipals/synchronizationSchema/manage
For credential management:
microsoft.directory/servicePrincipals/synchronizationCredentials/manage
3. Technical requirements from Guidde:
SCIM 2.0 endpoint URL (e.g., https://api.guidde.com/scim/v2)
Bearer token (secret token) from Guidde's admin console (provided by your CSM)
The endpoint must use HTTPS with TLS 1.2 and a certificate from an approved CA
4. Configure SAML SSO following the setup link received from your CSM.
5. The SCIM URL and Secret Token will be shared by your CSM in two separate emails.
Step 1: Enable Automatic Provisioning with Bearer Token Authentication
Bearer token authentication uses a long-lived secret token issued by Guidde rather than OAuth flows, making it the simplest authentication method for SCIM provisioning.
Navigation path: Guidde app → Manage → Provisioning → Get started
From your Guidde application's Overview page, open the Manage section.
Select Provisioning.
Click Get started
4. Add a new configuration
Configure Admin Credentials (received via email from your CSM):
Field | Value |
Tenant URL | Enter Guidde's SCIM endpoint URL (e.g., https://api.guidde.com/scim/v2) |
Secret Token | Paste the bearer token obtained from Guidde's CSM |
Standards-Compliant SCIM Note:
The Entra ID Tenant URL should always include the suffix:
`/?aadOptscim062020`
This flag is crucial as it notifies Microsoft Entra ID to use the standards-compliant SCIM behavior, which ensures correct operation formatting, especially for PATCH requests.
1. Click Test Connection - Microsoft Entra sends a GET request for a non-existent user to verify endpoint availability and credential validity.
2. Upon successful test (HTTP 200 with empty ListResponse).
3. Click Create.
Important note: Never leave the Secret Token field blank in production.
While Entra will generate its own OAuth token if empty, this approach is intended only for testing and may not work with third-party applications like Guidde.
Step 2: Create App Roles for userRole Attribute
App roles enable role-based access control provisioned via SCIM.
For Guidde's userRole attribute (Admin, ContentManager, Creator, Viewer), you'll define these roles in the application registration.
Navigation path: Entra ID → App registrations → Guidde → App roles
1. Navigate to Entra ID → App registrations.
2. Select your Guidde application (if no registration exists, click + New registration and create one linked to your enterprise app).
3. Under Manage, select App roles.
4. Click Create app role.
Configure Role definitions
Note: Ensure to copy-paste these values into the fields as they appear below.
Display Name | Value | Allowed Member Types | Description |
Admin | Admin | Users/Groups | Full administrative access to Guidde |
ContentManager | ContentManager | Users/Groups | Can manage and publish content |
Creator | Creator | Users/Groups | Can create and edit content |
Viewer | Viewer | Users/Groups | Read-only access to content |
5. Ensure Enable this role is checked for each role.
6. Click Apply to save each Access Guidde app role.
7. Repeat the steps per each role.
8. The added roles will now appear in the Enterprise Application for user assignment.
9. Delete the following roles (the previous default roles): User and MSIAM.
Note: This action deletes these roles for Guidde application only.
Step 3: Add custom SCIM Attributes to the Target Schema
Guidde requires two custom attributes not present in the default SCIM schema. You must extend the target attribute list before creating mappings.
Navigation path: Enterprise apps → Guidde app → Provisioning → Attribute mappings → Provision Microsoft Entra ID Users
1. In the Guidde enterprise app, access Provisioning.
2. Access Attribute mappings (preview).
3. Select Provision Microsoft Entra ID Users.
4. Scroll to the bottom and check Show advanced options.
5. Click Edit attribute list for customappsso (or your app's display name).
6. Scroll to the bottom of the attribute list and add each custom attribute:
Custom attributes to add:
Name | Type | Primary Key? | Required? |
userRole | String | No | No |
businessRole | String | No | No |
7. Click Save after adding both attributes.
Step 4: Configure Attribute Mappings for Custom Roles
With custom attributes defined, create the mappings that populate userRole from app role assignments and businessRole from a source attribute.
Return to: Guidde app → Provisioning → Attribute mappings → Provision Microsoft Entra ID Users
Mapping userRole from App Role Assignments:
1. Click Add New Mapping
2. Configure the mapping:
Mapping type: Expression
Expression: SingleAppRoleAssignment([appRoleAssignments])
Target attribute: userRole
Apply this mapping: Always
3. Click OK and approve any related permission prompts to save.
This expression extracts the single role value (Admin, ContentManager, Creator, or Viewer) assigned to each user and provisions it to Guidde.
Optional: Mapping businessRole from department or extension attribute (Fallback to “Other” if not provided).
Otherwise, Skip to step 6 below.
Expected Business Role Values
Marketing
Support
Human Resources
Sales
Customer Success
Operations
Learning and development
Product Management
IT
Other
For businessRole values like IT, HR, Finance, create a mapping based on your source data
Option A: Direct mapping from department:
Mapping type: Direct
Source attribute: department
Target attribute: businessRole
Option B: Expression with value transformation:
Switch([department], "General", "Information Technology", "IT", "Human Resources", "HR", "Finance", "Finance", "Engineering", "Engineering")
Option C: From extension attribute:
If businessRole is stored in an extension attribute (e.g., extension_abc123_businessRole), map it directly.
Set Apply this mapping to Always
Click OK then Save the mappings
Step 5: Assign Users and Groups with Roles
Users need to be assigned to the application with their appropriate userRole before provisioning occurs.
Navigation path: Guidde app → Manage → Users and groups
1. Select Users and groups under Manage.
2. Click + Add user/group .
3. Under Users and groups, select the users or groups to provision.
4. Click Select a role and choose the appropriate role (Admin, ContentManager, Creator, or Viewer).
5. Click Select.
6. Click Assign.
Important configuration: Set the provisioning scope to "Sync only assigned users and groups" in Provisioning → Settings. The SingleAppRoleAssignment expression function does not work with "Sync all users and groups" scope.
Step 6: Test Provisioning Before Deployment
On-demand provisioning validates your configuration without triggering a full sync cycle.
Navigation path: Guidde app → Provisioning - Provision on demand
1. Navigate to Provisioning.
2. Click Provision on demand.
3. Search for an assigned user by name or email.
4. Select the user and click Provision.
5. Review the output showing successful testing:
6. Expand Modified Properties to verify userRole and businessRole values appear correctly:
Sample SCIM payload to verify:
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:guidde:2.0:User"
],
"userName": "[email protected]",
"displayName": "John Smith",
"urn:ietf:params:scim:schemas:extension:guidde:2.0:User": {
"userRole": "Creator",
"businessRole": "IT"
}
}
Optional: Troubleshooting Common Issues
Understanding common failure patterns accelerates resolution when provisioning encounters problems.
Test Connection failures:
Error | Cause | Resolution |
Unable to connect | Invalid URL format or network issue | Verify URL format is https://..., no trailing slashes conflicting with Guidde's expected format |
Unauthorized (401) | Invalid or expired token | Generate a new bearer token from Guidde's admin console |
Certificate error | Invalid TLS certificate | Guidde must use HTTPS with TLS 1.2 from an approved CA |
Provisioning failures:
Error Code | Meaning | Resolution |
EntryConflict | User already exists with conflicting attribute | Check matching attribute configuration; user may exist with different identifier |
MandatoryFieldsMissing | Required attribute has no value | Ensure source attributes are populated; check mapping expressions |
SchemaAttributeNotFound | Target attribute doesn't exist in Guidde | Verify Guidde's SCIM endpoint supports the custom attribute name format you specified |
MultipleGrantsNotSupported | Using SingleAppRoleAssignment with multiple roles | Ensure each user has only one role, or switch to AppRoleAssignmentsComplex |
Provisioning logs analysis:
Navigate to Guidde app → Monitoring → Provisioning logs to review all operations. Each log entry shows the action (Create, Update, Delete), status, and detailed step-by-step breakdown. Failed entries include error codes and resolution recommendations in the Troubleshooting tab.
Quarantine state: If the provisioning service enters quarantine (indicated in the Overview), credentials are typically invalid or the endpoint is consistently failing. Re-test the connection and verify Guidde's SCIM endpoint status.
Best practices for sustainable SCIM provisioning
Following established patterns prevents common pitfalls and ensures reliable ongoing provisioning.
Always use "Sync only assigned users and groups" scope when using app role expressions—the role functions are incompatible with syncing all users
Test expression mappings with the Expression Builder before saving—access via Show advanced options → Expression builder, which allows testing with sample attribute values
Handle null values gracefully using Coalesce([primaryAttribute], [fallbackAttribute]) or IIF(IsPresent([attribute]), [attribute], "DefaultValue")
Document your custom schema extensions including the exact attribute names, types, and allowed values for future administrators
Monitor provisioning health weekly by reviewing the provisioning logs and checking for increased failure rates or new error patterns
Avoid frequent mapping changes as each modification triggers a full re-evaluation of all users in scope, which can take hours for large directories
Use the SCIM compatibility flag if experiencing issues with operation formatting: append ?aadOptscim062020 to your Tenant URL to ensure consistent PATCH operations
Configuration checklist
Pre-configuration:
Microsoft Entra ID P1/P2 license active
Application Administrator role assigned
Guidde SCIM endpoint URL obtained
Guidde bearer token generated
Application setup:
Non-gallery enterprise application created named "Guidde"
Provisioning mode set to Automatic
Tenant URL and Secret Token configured
Test Connection successful
Role and attribute configuration:
Four app roles created (Admin, ContentManager, Creator, Viewer)
Custom target attributes added (userRole, businessRole)
userRole mapped using SingleAppRoleAssignment([appRoleAssignments])
businessRole mapped from department or extension attribute
Provisioning scope set to "Sync only assigned users and groups"
Deployment:
Test users assigned with appropriate roles
Provision on demand tested successfully for sample users
Full provisioning started
Provisioning logs reviewed for any errors
This configuration enables fully automated user provisioning to Guidde with role-based access control, ensuring users receive appropriate permissions based on their Entra ID assignments.