Azure AD Quickstart
You will need:
- An account on the smallstep platform. Need one? Register here
- A Premium edition account (P1 or P2)
- Global administrator access to the account
- The Azure CLI (run
az loginto log in)
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 Groups
You'll grant access to your Hosts via user 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
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. Create an OAuth OIDC App
Create an App Registration
Due to a quirk in the Azure AD web portal, we must create our OAuth OIDC app on the command line. Run the following:
az ad app create --display-name "Smallstep SSH" --reply-urls http://127.0.0.1 --available-to-other-tenants true
Note: You are creating a multi-tenant app here, but Smallstep will only work within the Azure tenant ID you'll give us a bit later.
Now go back to your browser and go to App Registrations.
Back in App Registrations, choose the All Applications tab at the top.
Smallstep SSHapp you just created on the command line.
Note the Application (client) ID. You will need it in a moment.
Add a Client Secret
- Now choose Certificates & Secrets on the left.
- Under Client Secrets, make a + New client secret.
- Name doesn't matter
- Expires Never
- Save the secret
- Copy the value of the client secret you just created. You will need it in a moment.
Step 3. Enter your OIDC Details into the Smallstep SSH UI
Log in at
You should see the Welcome dialog. If the dialog does not open automatically, you can relaunch it from the “Resources” page.
Paste your Application (client) ID and Client secret into the Smallstep onboarding dialog box. The tenant ID is your Azure Active Directory tenant ID and is located on the overview blade for Azure Active Directory.
For the Configuration endpoint, use
Choose ENABLE SINGLE SIGN-ON
You've completed the OIDC portion of the setup.
Step 4. Create a SCIM application
Create an Enterprise Application
Back in the Azure portal, go to the Enterprise Applications blade.
Choose + New application.
Add a Non-Gallery Application.
smallstep-usersyncor some other name you'll remember.
Assign groups to your application
In your new application, under Users and Groups on the left:
- Go to + Add User to create a new assignment.
- Select your
- Choose Select on the bottom right.
- Choose Assign at the bottom left.
Your Users and Groups list should now look something like this:
Supply your SCIM credentials
- Back on your applications overview page, choose Provisioning on the left.
- Set the provisioning mode to Automatic.
- Under “Manage provisioning,” go to Update credentials.
- Expand Admin Credentials:
- Supply the SCIM Tenant URL and Secret Token from your activation email.
- Choose Test Connection and make sure that it works.
Set up attribute mappings
Smallstep needs to see the right attributes when you sync your directory with us.
- Expand Mappings.
- Choose Synchronize Azure Active Directory Users to customappsso
- Under the Attributes Mappings section, perform the following steps:
- Delete all attribute mappings except for
- Edit the
- Mapping Type: Expression
Item(Split([userPrincipalName], "@"), 1)
- Target Attributes:
- Match objects using this attribute: Yes
- Matching precedence: 1
- Delete all attribute mappings except for
Your mappings should look like this when you're finished:
Turn on Provisioning
- Save your settings and return to the Provisioning panel.
- Change Provisioning Status to On.
- 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 5. Confirm the directory connection
Sign in at
https://smallstep.com/app/[Team ID]. You should see your directory with users and groups synced.
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 checking ✅Clear current state and restart synchronization in the Provisioning panel, and choosing Save. Even then, it may take a minute to sync with Smallstep.
- 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 | firstname.lastname@example.org
- 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 | email@example.com