Azure AD Quickstart


You will need:

  • An account on the smallstep platform. Need one? Register here
  • An Azure Premium edition account (P1 or P2)
  • 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. Create Groups in Azure Active Directory
  2. Enter OIDC details into the Smallstep SSH UI
  3. Create a SCIM Application in Azure Active Directory
  4. Check logs to confirm users and groups are syncing to Smallstep SSH

Step By Step Instructions

Step 1. Create Groups

You'll grant access to your hosts via Active Directory Groups. If you don't already have groups set up, you'll want to create a group for each kind of user access to your servers. For example, you might have a group for ssh users, and one for sudo users.

In the Azure portal, start at the Groups blade.

When creating your groups, give them names and accept the defaults on all other settings.

Step 2. Tell us your Tenant ID

  1. In the Smallstep SSH dashboard, under the Users tab, choose Azure.

  2. Paste your Tenant ID from the Active Directory Overview blade into the "Add Your Team" dialog:

  3. Choose Save.

Step 3. Create a SCIM application

Create an Enterprise Application
  1. Back in the Azure portal, go to the Enterprise Applications blade.

  2. Choose + New application.

  3. Add a Non-Gallery Application.

  4. Call it smallstep-usersync or some other name you'll remember.

  5. Choose Next on the bottom left.

Assign groups to your application

In your new application, under Users and Groups on the left:

  1. Go to + Add User to create a new assignment.
  2. Select your sudo and ssh groups.
  3. Choose Select on the bottom right.
  4. Choose Assign on the bottom left.

Your Users and Groups list should now look something like this:

Supply your SCIM credentials
  1. Back on your applications overview page, choose Provisioning on the left and choose Get Started.
  2. Set the provisioning mode to Automatic.
  3. Under "Manage provisioning," go to Update credentials.
  4. Expand Admin Credentials:
    • Supply the SCIM Tenant URL and Secret Token from your activation email.
    • Choose Test Connection and make sure that it works.
    • Save.
Set up attribute mappings

Smallstep needs to see the right attributes when you sync your directory with us.

  1. Expand Mappings.
  2. Choose Provision Azure Active Directory Users
  3. Under the Attributes Mappings section, perform the following steps:
    1. Delete all attribute mappings except for userPrincipalName, displayName, mail, givenName, and surname
    2. Edit the userPrincipalName attribute.
      • Mapping Type: Expression
      • Expression: ToLower(Replace([userPrincipalName], , "(?<Suffix>@(.)*)", "Suffix", "", , ))
      • Target Attributes: userName
      • Match objects using this attribute: Yes
      • Matching precedence: 1
      • Apply this mapping: Always
      • Ok
    3. Add an active attribute.
      • Mapping Type: Expression
      • Expression: Not([IsSoftDeleted])
      • Target attribute: active
      • Match objects using this attribute: No
      • Apply this mapping: Always
      • Ok

Your mappings should look like this when you're finished:

Do you have dots in your Azure UPNs?

Linux usernames with . in them are not POSIX-compliant, though in practice dotted usernames work fine on many systems. If your UPNs contain dots, you can configure the userName mapping to remove them. Just use the following expression for your userName attribute: ToLower(Replace(Replace([userPrincipalName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), ".", , ,"", , ))

Turn on Provisioning
  1. Save your settings and return to the Provisioning panel.
  2. Change Provisioning Status to On.
  3. Choose Save

🤦‍♂️ 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 4. Confirm the directory connection

Sign in at[Team ID]

  • Navigate to the LOGS menu. You should see a list of success messages assocated with SCIM-SYNC catagory items.

  • Navigate to the USERS menu. If the onboarding dialog is open, press Esc to close.

  • You should see your Users and Groups synced over from Azure AD.

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.

Azure AD Configuration Complete

Troubleshooting Tips

  • Initial activation of Azure AD OIDC provisioning in Smallstep SSH requires entering your Application (client) ID, Client secret, and Configuration Endpoint into the Smallstep UI. Contact smallstep support with any questions |
  • Note: When users are deactivated in Azure AD, they will be deactivated in Smallstep. Users will not be able to SSH to servers, but their user accounts will remain on smallstep managed hosts. To permanently delete user data on smallstep managed hosts, contact Smallstep Support |

Unsubscribe anytime. See our privacy policy.