Azure Entra ID Provisioning

Once Microsoft Entra ID (formerly Azure AD) is wired up to TheStorage, your directory becomes the source of truth for who has an account. New hires land in TheStorage minutes after you assign them to the app, attribute changes flow through on each sync cycle, and offboarded employees are deactivated without anyone clicking a button.

The integration uses SCIM 2.0, the open standard for moving users between identity providers and applications. Beyond user accounts, the same connection manages who is allowed to do what: membership in four pre-defined Entra groups maps directly onto TheStorage roles (see Step 3). Profile photos are an optional extension that runs over Microsoft Graph — see Step 7 for the setup.

Requirements

• A Global Administrator or Application Administrator role in your Microsoft Entra tenant.
• A TheStorage user with the Administrator role (needed to generate the SCIM bearer token).
• A Microsoft Entra licence that includes automatic user provisioning (currently Entra ID P1 or higher).

Step 1: Generate the SCIM Credentials in TheStorage

There's no on/off switch for SCIM — the tenant endpoint is always reachable, and what actually controls inbound provisioning is whether a bearer token is configured. Until you generate one, the panel shows Not configured and every inbound call is rejected.

1. Sign in to TheStorage and open Settings > User Provisioning.

2. In the Authentication section, click Generate token. The new bearer token appears in a masked field — click the eye icon to reveal it, or Copy to grab it directly.

3. Stash the token somewhere safe — a password manager, or paste it straight into Step 15 below. TheStorage only keeps a hash, so once you navigate away the raw value is gone for good. The only way to see a token again is Regenerate token, which immediately invalidates the current one (your IdP gets 401 until the new value is pasted in).

4. In the Tenant endpoint section, click Copy next to the endpoint URL. It looks like:

   https://service.thestorage.app/api/<your-tenant>/scim/v2

   Keep both values to hand for the Entra configuration in Step 15.

Step 2: Create the Enterprise Application in Entra

5. Sign in to the Microsoft Entra admin center with an administrator account.

6. Navigate to Identity > Applications > Enterprise applications.

7. Click New application > Create your own application.

8. Configure:

   Field	Value
   Name	TheStorage SCIM Provisioning
   What are you looking to do with your application?	Integrate any other application you don't find in the gallery (Non-gallery)

9. Click Create and wait for the application to finish being created.

Step 3: Assign Users and Role Groups

This step decides both who gets synced and what they can do. TheStorage recognises four pre-defined group names, and a user's membership sets their role automatically on every sync. Assigning a group to the app also pulls its members into provisioning scope — so the same four groups do double duty, defining both who is provisioned and what role they get.

Turn on group-based roles first

Group membership drives roles only while your tenant's Role management setting is set to Identity provider groups. Open Settings > User Provisioning, find the Role management section ("Manage roles from"), and confirm it's set to Identity provider groups — the default and recommended choice for Entra. If it's set to In-app instead, the groups below still control provisioning scope but no longer assign roles; you'd manage roles by hand on the Users & Roles page. You can switch between the two modes at any time.

Entra group name	TheStorage role	What the role can do
TheStorage_Admins	Administrator	Everything, including Settings — the only role that can change tenant configuration, integrations, and billing.
TheStorage_Contributors	Contributor	Day-to-day inventory management: devices, categories, tags, places, vendors, campaigns, audits, users, and software — everything except Settings.
TheStorage_Supervisors	Supervisor	Oversight access: dashboard, devices, users, audits, software, and subscription pages. Cannot modify the catalog (categories, tags, places, vendors) or run campaigns.
TheStorage_Users	User	Employee self-service only: their personal My Devices page, audit self-verification, and the employee store.

10. In the Microsoft Entra admin center, go to Groups > All groups > New group and create four Security groups named exactly as in the table above.

    Group names must match exactly

    The names are matched case-insensitively, but the spelling has to be exact. TheStorage Admins (with a space) or TheStorageAdmins (without the underscore) will not be recognised, and members of a misspelled group silently fall back to the User role.

11. Add each employee to the group that matches the access they need. Anyone not placed in a group gets the User role by default, so you only need to populate the higher tiers.

12. Open the Enterprise Application you created in Step 2, go to Users and groups > Add user/group, and open the Groups tab. Tick the four TheStorage_* role groups, then click Select. Add any individual users who should be synced but don't belong to a role group here too.

    Roll out gradually

    Only assigned principals are provisioned. Start with a small test group, then widen the scope once the first sync succeeds.

How role assignment behaves

• Highest role wins. A user in both TheStorage_Admins and TheStorage_Users gets Administrator — the most powerful membership always takes precedence.
• No group means User. Removing someone from all four groups demotes them to the User role on the next sync; it does not deactivate their account.
• The tenant owner is protected. A group sync can never demote the tenant owner (the person who originally created the tenant), even if they're removed from every group — this prevents a directory mistake from locking everyone out of Settings.
• Only these four groups exist. The groups are managed by the platform: they can't be renamed, deleted, or extended with custom ones over SCIM. Membership in any other synced group is ignored.
• The in-app role control is read-only. While Role management is set to Identity provider groups, the Edit role control on the Users & Roles page is read-only — group membership is authoritative and re-applied on every sync. To change someone's access, move them between the groups above, or switch Role management to In-app if you'd rather assign roles in TheStorage. (The tenant owner is always editable in-app as a break-glass exception.)

Step 4: Connect Entra to TheStorage

13. Open Provisioning in the left-hand menu and click Get started, then set Provisioning Mode to Automatic.

14. Expand Admin Credentials and fill in:

    Field	Value
    Tenant URL	The endpoint URL from Step 4
    Secret Token	The bearer token from Step 3

15. Click Test Connection. Entra checks the endpoint and token and reports success. If it fails, double-check the endpoint URL (no trailing slash, correct tenant slug) and re-paste the token.

16. Click Save. Entra stores the configuration in a dormant state — nothing is pushed yet. The sync starts when you flip the switch in Step 19, so it's safe to save here and walk away if you need to.

Step 5: Review Attribute Mappings

17. Expand Mappings. Two mappings are created by default — Provision Azure Active Directory Users and Provision Azure Active Directory Groups.

18. Open the Users mapping and confirm the defaults match the attributes TheStorage expects:

    Entra attribute	SCIM attribute
    userPrincipalName	userName
    mail	emails[type eq "work"].value
    givenName	name.givenName
    surname	name.familyName
    displayName	displayName
    jobTitle	title
    department	department
    Switch([IsSoftDeleted], , "False", "True", "True", "False")	active

    Entra ships all of these as defaults except department — including the active mapping, so you don't need to add it. Add the department mapping yourself: it's optional, but recommended, since TheStorage uses it to group and filter people.

    Leave the Provision Azure Active Directory Groups mapping enabled with its defaults. TheStorage uses it to receive membership changes for the four pre-defined role groups (see Step 3) — that's what keeps user permissions in sync with your directory. Arbitrary groups outside the TheStorage_* set are not stored; Entra may log them as skipped, which is harmless.

Step 6: Turn Provisioning On

19. Back on the Provisioning overview page, set Provisioning Status to On and click Save.

20. Entra runs the first cycle within a few minutes. Use View provisioning logs to track progress; each user should reach the status Provisioned in target system.

21. Open TheStorage's Users page and confirm the assigned users appear with the Microsoft Entra badge — and that each shows the role matching their group membership from Step 3.

From here on, Entra runs an incremental sync roughly every 40 minutes. If you've just changed a mapping or a group membership and want to see the result without waiting, use Provision on demand from the application's Provisioning page to push a single user immediately.

Step 7 (Optional): Profile Photos via Microsoft Graph

Entra can't push the binary photo over SCIM — thumbnailPhoto isn't exposed as a source attribute, and there's no other photo source in the mapping UI. TheStorage works around this by pulling each photo directly from Microsoft Graph whenever a SCIM update arrives. You don't need any extra mapping on the Enterprise App side; you only need to connect a Microsoft Entra app registration in TheStorage so the photo sync has Graph credentials to use.

The connection lives on the same Settings > User Provisioning page, in the Microsoft Entra profile photos (optional) card.

The card only appears for Entra tenants

This card is shown only once TheStorage has detected Entra as your SCIM provider. Detection is automatic — TheStorage reads the connector's identity the first time Entra calls the endpoint (the Test Connection in Step 4, or the first sync in Step 6), so by this point the card is present. Google- and Okta-provisioned tenants never see it, because this Graph-based photo pull is Entra-specific. If you don't see the card yet, run Test Connection (Step 4) or Provision on demand once to let TheStorage detect the provider.

If the card already shows a green Connected badge from a previous integration, you're done — photos arrive on the next sync. Otherwise, follow the steps below. You'll be moving between two browser tabs (the Azure portal and TheStorage), so open both before you start.

Create the App Registration in Azure

22. In TheStorage, open Settings > User Provisioning, scroll to the Microsoft Entra profile photos (optional) card, and click Connect Entra. The Microsoft Entra Connect dialog opens with three empty fields — Entra Tenant URL, Client Id, and Secret key. Leave it open in a second tab; you will paste values into it as you go.

23. In a new tab, open the Azure portal and sign in with an account that has at least the Application Administrator role.

24. From Azure services, choose Microsoft Entra ID (formerly Azure Active Directory).

25. In the left sidebar, select App registrations, then click + New registration at the top of the page.

    Why a separate app registration?

    The Enterprise Application from Step 2 can't be reused here — the two apps run in opposite directions. The Enterprise App holds a bearer token so Entra can push users to TheStorage; the App Registration you're about to create holds a client secret so TheStorage can pull from your tenant over Microsoft Graph. The Non-gallery flow you used in Step 2 also produces a service-principal-only entry, which can't host the client secrets and Graph permissions this side needs.

26. Configure:

    Field	Value
    Name	TheStorage Photo Sync
    Supported account types	Accounts in this organizational directory only (Single tenant)
    Redirect URI	Leave blank

    Click Register. Azure provisions the application and opens its overview page.

Copy the Client ID and Tenant Domain

27. On the Overview page, copy the Application (client) ID into the dialog's Client Id field, and your tenant's Primary domain (the *.onmicrosoft.com value, also shown on the Entra overview) into the Entra Tenant URL field. The Directory (tenant) ID GUID works there too, if you prefer it over the domain.

Create a Client Secret

28. In the sidebar of the app registration, click Certificates & secrets, then under the Client secrets tab click + New client secret.

29. Configure:

    Field	Value
    Description	TheStorage Photo Sync
    Expires	24 months (the longest Azure allows; pick a shorter window only if your security policy requires it)

    Click Add.

30. Azure now shows the new secret with a Value column. Copy the Value (not the Secret ID) immediately and paste it into the Secret key field on the TheStorage tab.

    warning

    Azure shows the secret value exactly once. Navigate away from this page and the value is permanently masked — there's no way to retrieve it later. If you miss the copy, delete the secret and create a new one.

Grant API Permissions

31. In the sidebar, click API permissions, then + Add a permission.

32. Choose Microsoft Graph at the top of the Request API permissions panel.

33. Pick Application permissions (not Delegated).

34. In the search box, type Directory.Read.All and tick the checkbox. Then type User.Read.All and tick that one as well. Click Add permissions.

    Why two permissions?

    Directory.Read.All lets TheStorage enumerate users and groups for directory sync. User.Read.All is the lowest scope that covers /users/{id}/photo/$value, the endpoint used to fetch each user's photo. Skip the second one and photo requests return 403.

35. Back on the API permissions page, click Grant admin consent for <your tenant> and confirm with Yes in the dialog. The Status column should change to a green check on both rows.

Save the Connection in TheStorage

36. Back in the TheStorage tab, all three fields should now be populated. Click Connect. TheStorage validates the credentials against your tenant before storing them — the button reads Connecting while the check runs. On success the dialog closes and the card shows a green Connected badge; on failure an error appears inside the dialog. The usual suspects are missing admin consent (Step 35), a typo in one of the values, or pasting the secret's ID instead of its value.

37. That's it — photos ride along with SCIM updates from here on. Trigger Provision on demand in Entra for a test user who has a photo set, and it appears on their TheStorage profile within one cycle.

Plan for the secret to expire

The client secret behind the Entra connection is what TheStorage uses to call Graph, and Azure client secrets are short-lived — at most 24 months, often less depending on your tenant policy. When it expires, SCIM user provisioning keeps working, but photo sync goes quiet. The failure shows up in TheStorage's server logs, not in Entra's provisioning logs, so it's easy to miss.

Set a calendar reminder for two weeks before the expiry date. When it fires, generate a fresh secret in the Azure portal, then open Settings > User Provisioning, click Connect Entra on the profile photos card, and re-enter the credentials with the new secret value.