Merge pull request #449 from smallstep/carl/entra-usersync

Entra ID user sync docs

Author: tashian

graphics/entra-id-mappings.png

@@ -79,8 +79,12 @@
           "title": "Add Users to Smallstep",
           "routes": [
             {
-              "title": "Sync Okta Users (SCIM)",
+              "title": "Sync Okta Users",
               "path": "/tutorials/sync-okta-users-to-smallstep.mdx"
+            },
+            {
+              "title": "Sync Entra ID Users",
+              "path": "/tutorials/sync-entra-id-users-to-smallstep.mdx"
             }
           ]
          },

manifest.json

@@ -0,0 +1,106 @@
+---
+updated_at: October 30, 2025
+title: Sync Entra ID Users to Smallstep
+html_title: Sync Microsoft Entra ID Users to Smallstep
+description: Integrate Smallstep with Microsoft Entra ID, syncing identity provider users for device identity.
+---
+
+### Prerequisites
+
+You will need:
+
+* A Smallstep team. [Register here](https://smallstep.com/signup)
+* An Entra ID tenant with subscription P1 or higher
+* Global Administrator access to the account
+
+### Features
+
+The following provisioning features are supported:
+
+* Push Groups and New Users
+* Push Profile or Group Updates
+* Push User Deactivation
+* Reactivate Users
+
+## Step By Step Instructions
+
+### Step 1. Create an Entra ID Enterprise Application
+
+1. In Entra ID, visit [Browse Entra Gallery](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2) and choose “+ Create your own application”.
+2. Name the application and use the default “Non-gallery” option.
+3. In your new Enterprise Application, visit Manage → Users and groups.
+4. Assign the groups or users you’d like to sync to Smallstep. You may want to create new groups for Smallstep users.
+
+### Step 2. Enable SSO
+
+#### In Entra ID
+
+1. Your Enterprise Application comes with an App Registration.
+2. Go to [App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and find your Smallstep application in the list.
+3. In the App Registration, visit “Manage → Certificates & secrets”
+4. Create a new Client Secret
+5. Set the client secret description and expiry as desired
+6. Save the Client ID and Client Secret Value for later
+7. Look up your directory's Tenant ID, and save it for later
+
+##### In Smallstep
+
+1. Go to [Connect an Entra ID IdP](https://smallstep.com/app/?next=/settings/users/identity-providers/azuread/connect)
+2. Fill the Client ID, Client Secret, and Tenant ID you saved.
+
+
+### Step 3. Enable User Provisioning
+
+1. Smallstep will send you a SCIM URL and Secret Token.
+2. In Entra ID, return to your Smallstep Enterprise Application.
+3. Go to Manage → Provisioning
+4. Set the provisioning mode to **Automatic**.
+5. Expand **Admin Credentials:**
+    - Supply the SCIM **Tenant URL** and **Secret Token** you received from Smallstep.
+    - Choose **Test Connection** and make sure that it works.
+    - Save.
+
+### Step 4. Turn on Provisioning
+
+1. Return to the **Provisioning** panel.
+2. Choose **Start Provisioning**.
+
+> 🤦‍♂️ There’s a quirk in Microsoft’s UI here, and you may see an error when saving after turning provisioning on. If so, wait 60 seconds and try Save again.
+> 
+
+### Step 5. Adjust user attribute mappings
+
+1. In your Smallstep Enterprise Application, the Manage → Attribute Mappings blade should now be accessible. Choose it.
+2. Choose “Syncronize Entra ID Active Directory Users to customappsso”
+3. The mappings you’ll want for Smallstep are:
+    
+    ![Entra ID mappings](/graphics/entra-id-mappings.png)
+    
+    Most of these are part of the default mappings.
+    
+    The only two you will need to customize are:
+    
+    - If you're using Smallstep SSH, the `userName` attribute determines the name of a user’s POSIX account. Update  `userName` to map to `ToLower(Replace([userPrincipalName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), )`.
+    - Add `externalId`, with a mapping to `objectId`. This should be a unique ID representing the user that is not reusable.
+
+4. Remove any other default attributes that are not in the list above. The only attributes you need to send to Smallstep are:
+    - `userName`
+    - `displayName`
+    - `emails[type eq "work"].value`
+    - `name.givenName`
+    - `name.familyName`
+    - `externalId`
+5. Save your user attribute mappings.
+
+### Step 6. Confirm the directory connection
+
+1. Return to the Smallstep dashboard.
+2. In the Users tab, you should now see your Entra ID users
+3. Sign out
+4. You should be offered the option to sign in with SSO.
+5. Finally, let Smallstep know which of your SSO users should be team Owners or Admins in Smallstep.
+    - Admins have dashboard read/write privileges (users, devices, etc.)
+    - Owners have all the same privileges as Admins, with the additional privilege that Owners can create Admins.
+
+> **Don't see your users and groups?** Microsoft's SCIM service may add a 40-minute delay after you set it up. You can force an update by clicking **Restart provisioning** in the Provisioning panel. Even then, it may take a minute to sync with Smallstep.
+