Set up SAML single sign-on and SCIM provisioning so your identity provider controls who can sign in to Windmill and keeps member profiles, managers, and groups in sync.
Windmill supports SAML 2.0 single sign-on (SSO) so your team signs in through your company’s identity provider (IdP). Okta and Microsoft Entra ID are fully tested. Any SAML 2.0 compliant provider should work.SCIM 2.0 (System for Cross-domain Identity Management) builds on SSO. With SCIM, your identity provider creates members, keeps their profile fields and managers up to date, archives people who leave, and syncs groups into Windmill.This article covers the setup in Windmill. For the identity provider side, use the guide for your provider:
Set up SCIM with Okta
Turn on provisioning, map profile fields in the Profile Editor, and push groups.
Set up SCIM with Microsoft Entra ID
Turn on provisioning, add the Windmill attributes, and assign users and groups.
SCIM attributes and field sources
Every field SCIM can sync, the exact attribute names, and how SCIM works with field sources.
Sync groups from your identity provider
Bring identity provider groups into Windmill Groups for pulse surveys and review cycles.
Admin, HR Admin, or Integration Manager access to your Windmill account
Admin access to your identity provider (Okta, Microsoft Entra ID, etc.)
Rippling requires exclusive control over user provisioning. If you connect Rippling, SCIM is automatically turned off if it was on, and you can’t set up SCIM while Rippling is connected.
Go to Settings > Security and select Set up SSO to open the setup wizard. The wizard has three steps.
1
Service provider
Windmill displays your Entity ID (Audience URI), ACS URL, and Login URL. Copy these values into your identity provider’s SAML application settings, or select Download SP Metadata XML to download the metadata file.The wizard also shows the expected attribute mappings (firstName → user.firstName, lastName → user.lastName) and the Name ID format (EmailAddress).
The Service provider step displays the values you need to configure your identity provider.
2
Identity provider
After you configure your identity provider, give Windmill your SAML metadata so it can recognize sign-in requests. Paste a metadata URL or upload the XML file.
Provide your IdP metadata via URL or XML upload.
3
Test sign-in
Select Test SSO. Windmill redirects you to your identity provider to sign in. Windmill activates SSO after the first successful sign-in.
Once SSO is active, it’s enforced for all users. Google and Microsoft social login are turned off. There is no fallback. If your identity provider goes down or SSO is misconfigured, no one (including admins) can sign in until the issue is resolved. Make sure the test sign-in works before you roll SSO out to your team.
After activation, the Security page shows your SSO status and configuration. Use Update metadata if your identity provider’s certificate or metadata changes. To turn SSO off, contact support@gowindmill.com.
After activation, your security settings display the SSO configuration and the SCIM setup card.
SCIM requires an active SSO connection. If SSO isn’t active yet, the SCIM card shows Test SSO sign-in first.Setup takes two steps in Windmill and one in your identity provider. You don’t need to come back to Windmill to turn provisioning on. Windmill turns it on automatically when your identity provider connects.
1
Generate a SCIM token
In Settings > Security, select Set up SCIM, then Generate token. Windmill displays the Secret token and Tenant URL you need for your identity provider.
The token is displayed once. Copy it now and store it securely. If you lose it, generate a new one and update your identity provider.
Copy the Secret token and Tenant URL before you close this dialog.
2
Paste the token and Tenant URL into your identity provider
Follow the guide for your provider: Okta or Microsoft Entra ID. Use the Tenant URL as the SCIM base URL and the Secret token as the bearer token.
3
Wait for your identity provider to connect
The SCIM card shows Waiting for your identity provider. When your identity provider sends its first successful request, for example a connection test or the first user push, Windmill turns provisioning on and the status changes to Active.You have 24 hours after you generate the token to connect. If the window closes first, the status changes to Setup window expired. Select Regenerate token and paste the new token into your identity provider.
You don’t have to wait for the identity provider. Select Turn on now on the SCIM card to turn provisioning on immediately.
Pause provisioning. Turn off the Provisioning is on toggle. Windmill rejects requests from your identity provider, but existing members keep their access. Your identity provider shows errors until you turn provisioning back on.
Resume provisioning. Turn the toggle back on. Windmill applies the latest values it received from your identity provider to every provisioned member. See SCIM attributes and field sources.
Regenerate the token. The old token stops working immediately. Paste the new token into your identity provider. Regenerating a token doesn’t turn a paused connection back on.
Remove SCIM. Deletes the SCIM configuration and token. Members provisioned through SCIM keep their access, and manual invitations become available again.
SCIM keeps four things in sync from your identity provider:
Members. Who has access to Windmill.
Profile fields. Name, work email, job title, job level, start date, pronouns, gender, work phone, and profile picture. See SCIM attributes and field sources.
Existing members are linked, not duplicated. If a person with the same work email already has access to Windmill, SCIM links the identity provider record to that member.
Archived members are reactivated when your identity provider provisions them again, for example when you re-assign the Windmill app to them.
Deprovisioned members are archived when your identity provider deactivates or deletes them. Windmill signs them out, and their reviews, feedback, and notes are preserved. Access to any other Windmill account is unaffected.
SCIM provisioning does not send welcome messages by default. Turn on onboarding notifications in Settings > Security to notify provisioned members automatically. You can also send welcome messages manually from the Members page.
Windmill treats SCIM as a field source, the same way it treats your HRIS or Slack. SCIM stores every value your identity provider sends. It writes a value to an employee’s profile only when SCIM is the source for that field.
Fields with no source set are claimed by SCIM the first time it sends a value.
Fields owned by another source, like job level from your HRIS, keep the other source’s value. SCIM stores its value in the background.
When you switch a field to SCIM in Settings > Org Chart, Windmill applies the latest stored value within a few minutes. You don’t need to trigger a new push from your identity provider.
Test SSO before you roll it out. There’s no fallback if something goes wrong. Make sure the test sign-in works first.
Copy the SCIM token immediately. It’s only displayed once. If you lose it, regenerate it and update your identity provider.
Connect your identity provider within 24 hours. The token’s setup window closes after 24 hours. If it does, regenerate the token.
Decide which system owns each field. If you also connect an HRIS, review field sources so SCIM and your HRIS don’t both try to manage the same field.
Use identity provider groups to manage Windmill Groups. Managing group membership in your identity provider is easier than maintaining groups manually in Windmill.
Don’t use both Rippling and SCIM. They’re mutually exclusive. If you use Rippling for provisioning, continue using Rippling.
I'm locked out after activating SSO. What do I do?
Contact Windmill support at support@gowindmill.com to have SSO turned off for your account.
I lost my SCIM token. How do I get a new one?
Select Regenerate token on the SCIM card in Settings > Security. The old token stops working immediately, so update your identity provider right away.
The SCIM card says the setup window expired. What happened?
Your identity provider didn’t send a request within 24 hours of the token being generated. Select Regenerate token, paste the new token into your identity provider, and run a connection test or assign a user. Windmill turns provisioning on when the first request arrives.
My identity provider shows an error that says SCIM provisioning is paused.
Provisioning was turned off in Windmill. Turn the Provisioning is on toggle back on in Settings > Security. Windmill then accepts requests again and applies the latest values.
We already have members in Windmill. Will SCIM create duplicates?
No. When your identity provider pushes a person whose work email already belongs to a Windmill member, SCIM links to that member. Their history, reviews, and 1:1s stay in place.
Can I still invite members manually while SCIM is active?
No. When provisioning is on, your identity provider is the only way to add members. Assign the Windmill app to the person in your identity provider instead.
Users aren't being created on first SSO login. What's wrong?
First, check whether SCIM is active. When SCIM is active, the identity provider must provision the member before they sign in. Without SCIM, verify that the identity provider sends the NameID attribute in the SAML assertion.
Do SCIM-provisioned users get an invite email or Slack message?
Not by default. Turn on onboarding notifications in Settings > Security to notify provisioned members automatically. Use Send welcome message on the Members page to notify existing members by email, Slack, or both.
If I connect Okta, do members automatically get invited or messaged?
No. With Okta SAML SSO, members can be created when they first sign in, but Windmill does not send invite emails or Slack messages because of that. With Okta SCIM provisioning, members are created silently unless you turn on onboarding notifications.
A profile field from my identity provider isn't showing up in Windmill.
Check three things. First, the attribute is mapped in your identity provider with the exact name and namespace from SCIM attributes and field sources. Second, SCIM is the source for that field in Settings > Org Chart. Third, the employee doesn’t have a per-person override that points the field at another source.
I see a conflict error when setting up SCIM with Rippling connected.
SCIM and Rippling provisioning can’t be used together. Disconnect Rippling before you set up SCIM, or continue using Rippling to manage access.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.
