Skip to content

Updates to Entra ID tutorial #482

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tashian wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Updates to Entra ID tutorial #482

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 27 additions & 16 deletions tutorials/sync-entra-id-users-to-smallstep.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
updated_at: October 30, 2025
updated_at: January 21, 2026
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.
Expand Down Expand Up @@ -28,6 +28,7 @@ The following provisioning features are supported:

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.
* If the "Smallstep SSH" Marketplace app is shown, do not choose it.
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.

Expand All @@ -36,12 +37,22 @@ The following provisioning features are supported:
#### 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
2. Go to [App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and find your Smallstep application in the list. It may be under the "All Applications" tab.
3. On the application overview, save the Application (client) ID and Directory (tenant) ID for later.
4. In the App Registration, visit “Manage → Certificates & secrets”
5. Create a new Client Secret
6. Set the client secret description and expiry as desired
7. Save the Client Secret Value for later
8. Go to the API Permissions blade
9. Choose Microsoft Graph
10. Choose Delegated Permissions
11. Under OpenID Permissions, select `email`, `openid`, and `profile`.
12. Choose "Grant Admin Consent" for all permissions
13. Go to the "Token configuration" blade
14. Choose **Add Optional Claim**
* **ID** token type
* Select **email** and **preferred_username**
* Choose **Add**

##### In Smallstep

Expand All @@ -54,8 +65,9 @@ The following provisioning features are supported:
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:**
4. Create a new provisioning configuration.
6. For **Admin Credentials:**
- Use **Bearer Authentication**
- Supply the SCIM **Tenant URL** and **Secret Token** you received from Smallstep.
- Choose **Test Connection** and make sure that it works.
- Save.
Expand All @@ -65,23 +77,19 @@ The following provisioning features are supported:
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”
2. Choose “Provision Microsoft Entra ID Users"
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:
The only one you will need to customize is:

- 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.
- `externalId` should map to `objectId`. This is 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`
Expand All @@ -91,6 +99,9 @@ The following provisioning features are supported:
- `name.familyName`
- `externalId`
5. Save your user attribute mappings.
6. Change "Provisioning Status" to "On", and save the settings.

It may take up to 40 minutes to enable provisioning.

### Step 6. Confirm the directory connection

Expand Down