Sync Entra ID Users to Smallstep

You will need:

• A Smallstep team. Register here
• An Entra ID tenant with subscription P1 or higher
• Global Administrator access to the account

The following provisioning features are supported:

• Push Groups and New Users
• Push Profile or Group Updates
• Push User Deactivation
• Reactivate Users

1. In Entra ID, visit Browse Entra Gallery 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.

1. Your Enterprise Application comes with an App Registration.
2. Go to App registrations 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
   • Set the client secret description and expiry as desired
   • Save the Client Secret Value for later
6. Go to the API Permissions blade
7. Choose Microsoft Graph
8. Choose Delegated Permissions
   • Under OpenID Permissions, select email, openid, and profile.
   • Choose "Grant Admin Consent" for all permissions
9. Go to the "Token configuration" blade
10. Choose Add Optional Claim
    • ID token type
    • Select email and preferred_username
    • Choose Add
11. Go to Manage -> Authentication blade and choose + Add Redirect URI
    • Choose type "Web" and enter the URL: https://api.smallstep.com/auth/openid/callback
    • Choose "Configure"
12. Now choose the Settings tab in the Authentication blade.
    • Under Supported Account Types, select multi-tenant.
    • Only the users
    • Choose Save
13. Finally, return to the Overview blade.
14. Select 🌐Endpoints and copy the OpenID Connect metadata document URL for later.

1. Go to Connect an Entra ID IdP
2. Fill the Client ID, Client Secret, Tenant ID, and OIDC metadata URL you saved.

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. Create a new provisioning configuration.
5. 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.

1. Return to the Provisioning panel.
2. Choose Start Provisioning.

1. In your Smallstep Enterprise Application, the Manage → Attribute Mappings blade should now be accessible. Choose it.

2. Choose “Provision Microsoft Entra ID Users"

3. The mappings you’ll want for Smallstep are:

   

   Most of these are part of the default mappings.

   Two of them need to be customized:

   • externalId should map to objectId. This is a unique ID representing the user that is not reusable.
   • emails[type eq "work"].value should map to the expression Coalesce([mail],[userPrincipalName]). Entra maps this attribute to mail by default, including in the screenshot above; change the Mapping type from Direct to Expression to replace it.

   Why not map emails[type eq "work"].value straight to mail? Microsoft documents that the mail attribute "is only populated if the user has a Microsoft Exchange Mailbox," and Entra skips null attributes rather than sending them. Users without a mailbox — contractors, service accounts, shared and bot accounts — therefore sync to Smallstep with no email address at all. Smallstep matches SSO logins by email address, so those users appear in your directory looking correctly provisioned, but signing in fails with "You are not authorized to access this account." Coalesce falls back to userPrincipalName, which every user has, so nobody syncs without an email address.

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.

6. Change "Provisioning Status" to "On", and save the settings.

7. If you changed a mapping on a configuration that had already synced users, choose Restart provisioning in the Provisioning panel. Entra only sends users it considers changed, so users that synced under the old mappings are not re-sent otherwise. To check the new mapping against a single user first, use Provision on demand.

It may take up to 40 minutes to enable provisioning.

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.

A synced user can't sign in with SSO? If a user reaches Smallstep after signing in to Entra but is told "You are not authorized to access this account," check that user in the Users tab. If they have no email address listed, they were provisioned without one and Smallstep can't match them to the account they signed in with. Correct the emails[type eq "work"].value mapping in Step 5, then Restart provisioning.