|
| 1 | +--- |
| 2 | +updated_at: October 30, 2025 |
| 3 | +title: Sync Entra ID Users to Smallstep |
| 4 | +html_title: Sync Microsoft Entra ID Users to Smallstep |
| 5 | +description: Integrate Smallstep with Microsoft Entra ID, syncing identity provider users for device identity. |
| 6 | +--- |
| 7 | + |
| 8 | +### Prerequisites |
| 9 | + |
| 10 | +You will need: |
| 11 | + |
| 12 | +* A Smallstep team. [Register here](https://smallstep.com/signup) |
| 13 | +* An Entra ID tenant with subscription P1 or higher |
| 14 | +* Global Administrator access to the account |
| 15 | + |
| 16 | +### Features |
| 17 | + |
| 18 | +The following provisioning features are supported: |
| 19 | + |
| 20 | +* Push Groups and New Users |
| 21 | +* Push Profile or Group Updates |
| 22 | +* Push User Deactivation |
| 23 | +* Reactivate Users |
| 24 | + |
| 25 | +## Step By Step Instructions |
| 26 | + |
| 27 | +### Step 1. Create an Entra ID Enterprise Application |
| 28 | + |
| 29 | +1. In Entra ID, visit [Browse Entra Gallery](https://portal.azure.com/#view/Microsoft_AAD_IAM/AppGalleryBladeV2) and choose “+ Create your own application”. |
| 30 | +2. Name the application and use the default “Non-gallery” option. |
| 31 | +3. In your new Enterprise Application, visit Manage → Users and groups. |
| 32 | +4. Assign the groups or users you’d like to sync to Smallstep. You may want to create new groups for Smallstep users. |
| 33 | + |
| 34 | +### Step 2. Enable SSO |
| 35 | + |
| 36 | +#### In Entra ID |
| 37 | + |
| 38 | +1. Your Enterprise Application comes with an App Registration. |
| 39 | +2. Go to [App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and find your Smallstep application in the list. |
| 40 | +3. In the App Registration, visit “Manage → Certificates & secrets” |
| 41 | +4. Create a new Client Secret |
| 42 | +5. Set the client secret description and expiry as desired |
| 43 | +6. Save the Client ID and Client Secret Value for later |
| 44 | +7. Look up your directory's Tenant ID, and save it for later |
| 45 | + |
| 46 | +##### In Smallstep |
| 47 | + |
| 48 | +1. Go to [Connect an Entra ID IdP](https://smallstep.com/app/?next=/settings/users/identity-providers/azuread/connect) |
| 49 | +2. Fill the Client ID, Client Secret, and Tenant ID you saved. |
| 50 | + |
| 51 | + |
| 52 | +### Step 3. Enable User Provisioning |
| 53 | + |
| 54 | +1. Smallstep will send you a SCIM URL and Secret Token. |
| 55 | +2. In Entra ID, return to your Smallstep Enterprise Application. |
| 56 | +3. Go to Manage → Provisioning |
| 57 | +4. Set the provisioning mode to **Automatic**. |
| 58 | +5. Expand **Admin Credentials:** |
| 59 | + - Supply the SCIM **Tenant URL** and **Secret Token** you received from Smallstep. |
| 60 | + - Choose **Test Connection** and make sure that it works. |
| 61 | + - Save. |
| 62 | + |
| 63 | +### Step 4. Turn on Provisioning |
| 64 | + |
| 65 | +1. Return to the **Provisioning** panel. |
| 66 | +2. Choose **Start Provisioning**. |
| 67 | + |
| 68 | +> 🤦♂️ 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. |
| 69 | +> |
| 70 | +
|
| 71 | +### Step 5. Adjust user attribute mappings |
| 72 | + |
| 73 | +1. In your Smallstep Enterprise Application, the Manage → Attribute Mappings blade should now be accessible. Choose it. |
| 74 | +2. Choose “Syncronize Entra ID Active Directory Users to customappsso” |
| 75 | +3. The mappings you’ll want for Smallstep are: |
| 76 | + |
| 77 | +  |
| 78 | + |
| 79 | + Most of these are part of the default mappings. |
| 80 | + |
| 81 | + The only two you will need to customize are: |
| 82 | + |
| 83 | + - 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", "", , ), )`. |
| 84 | + - Add `externalId`, with a mapping to `objectId`. This should be a unique ID representing the user that is not reusable. |
| 85 | + |
| 86 | +4. Remove any other default attributes that are not in the list above. The only attributes you need to send to Smallstep are: |
| 87 | + - `userName` |
| 88 | + - `displayName` |
| 89 | + - `emails[type eq "work"].value` |
| 90 | + - `name.givenName` |
| 91 | + - `name.familyName` |
| 92 | + - `externalId` |
| 93 | +5. Save your user attribute mappings. |
| 94 | + |
| 95 | +### Step 6. Confirm the directory connection |
| 96 | + |
| 97 | +1. Return to the Smallstep dashboard. |
| 98 | +2. In the Users tab, you should now see your Entra ID users |
| 99 | +3. Sign out |
| 100 | +4. You should be offered the option to sign in with SSO. |
| 101 | +5. Finally, let Smallstep know which of your SSO users should be team Owners or Admins in Smallstep. |
| 102 | + - Admins have dashboard read/write privileges (users, devices, etc.) |
| 103 | + - Owners have all the same privileges as Admins, with the additional privilege that Owners can create Admins. |
| 104 | + |
| 105 | +> **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. |
| 106 | +
|
0 commit comments