Skip to main content

SCIM (System for Cross-domain Identity Management)

The SCIM integration allows clients to automate user provisioning and de-provisioning. It enables Identity Providers (IdPs) like Microsoft Entra ID (Azure AD) and Okta to manage users and groups within the 5app Hub automatically.

Supported Features​

  • Core User Schema: Full CRUD support via /Users endpoint.

    • POST: Create new users.
    • GET: Retrieve individual users or list/filter users.
    • PATCH: Update user attributes and active status.
    • DELETE: In our implementation, soft-delete users (setting is_deleted: 1).

  • Enterprise User Extension: Supports organizational data: employeeNumber, costCenter, organization, division, department, and manager.

  • Group Management: Full CRUD support via /Groups endpoint.

    • POST: Create new teams.
    • GET: List groups (with displayName filtering) and retrieve membership lists.
    • PATCH: Primary method for membership updates. Supports add, remove, and replace operations for the members attribute, as well as replace for a team displayName. Only users added via SCIM to a team can be removed from a team via PATCH.
    • DELETE: Permanently removes or soft-deletes the team and it's team members, including members added to a team manually (not via SCIM)

  • Filtering: Supports eq (equals), co (contains), sw (starts with), and ew (ends with) filters for finding users/groups

    • Result sets are capped at 1000 items per page.

Implementation Details​

The SCIM API is implemented as part of our main API service under the /api/scim/v2 prefix.

  • Spec Compliance: Following RFC 7643 (Schema) and RFC 7644 (Protocol).
  • Authentication: Uses OAuth 2.0 Bearer Tokens. Tokens are generated per-domain.

Mapping Custom Attributes in Entra ID​

By default, Entra ID only syncs a basic set of attributes. To sync our extended fields (like city, jobTitle, or extendedAttribute1), you must manually map them in the Dev application:

  1. Open Attribute Mappings: In the Dev app, go to Provisioning > Edit Provisioning > Mappings > Provision Microsoft Entra ID Users.

  2. Edit Attribute List: Scroll to the bottom, check Show advanced options, and click Edit attribute list for CustomAppsSSO.

  3. Add the URN: Add a new entry using our custom URN format:

    • urn:ietf:params:scim:schemas:extension:fiveappext:2.0:User:city
    • urn:ietf:params:scim:schemas:extension:fiveappext:2.0:User:jobTitle

  4. Map the Field: Save the list, then back in the main Mapping screen, link the Entra ID source attribute (e.g., jobTitle) to your newly created target URN.

Internal Discovery Endpoints​

Developers can check the following endpoints to see the current server configuration:

  • /api/scim/v2/ServiceProviderConfig - View supported features (Patch, Filter, etc.)
  • /api/scim/v2/Schemas - View the active JSON schemas for Users and Groups.
  • /api/scim/v2/ResourceTypes - View endpoint mappings.

Development & Testing​

We use a dedicated Microsoft Entra account for integration testing.

  • Tenant: 5appms.onmicrosoft.com
  • Enterprise Application: Look for the app named "Dev" under Enterprise Applications > All Applications in the Azure Portal.
  • Manual Sync: To test changes immediately without waiting for the sync cycle, use the "Provision on Demand" feature within the "Dev" app settings.
  • Verification: Changes provisioned via the "Dev" app can be checked in https://dev.fiveapp.com/

Troubleshooting​

If provisioning fails, check the Provisioning Logs in the Entra ID app.

Common issues include:

  • Target Not Found (404): The Hub thinks the user/group is deleted. Check is_deleted in the DB.
  • Attribute Mismatch: If a field like jobTitle is empty in the Hub, verify the URN in the "Attribute Mapping" section matches our code.
  • Token Rejected (401): Re-generate a SCIM token from the Hub Admin panel for the domain.

Further Resources​