Skip to main content

SAML & SCIM

Setting up SAML and SCIM allows you to authenticate users using your identity provider.

This feature is available under Enterprise Edition. Configuration is set from Instance settings

SAML​

The entity ID is windmill

ACS Url is <instance_url>/api/saml/acs SCIM connector is <instance_url>/api/scim Application username format is Email

Instance settings UI

In the Instance settings UI, pass the SAML Metadata URL (or content) containing the metadata URL (or XML content).

Windmill takes the user's email from the NameID. If your identity provider sends a username as NameID and the email in an attribute, set the SSO email claim to that attribute, and the SSO username claim to NameID to keep it as the username.

tip

You can control the entity ID using the SAML_AUDIENCE environment variable. This can be useful if you want to use the same identity provider for multiple instances (e.g dev / prod).

Private or internal IdP metadata URLs​

By default, Windmill blocks SAML metadata URLs that resolve to private or internal network addresses to protect against server-side request forgery (SSRF). If your identity provider is only reachable on a private IP with no public DNS, the server rejects the metadata URL at load time and fails to start.

To allow private metadata URLs, set the ALLOW_PRIVATE_SAML_METADATA_URLS=true environment variable on the server. Only enable it when the metadata URL points to an identity provider you trust.

Alternatively, if you cannot expose the IdP metadata over a URL, paste the XML content directly in the field instead of a URL. Content passed inline is not subject to the SSRF check.

Okta​

Configure Okta with the following settings (and replace cf.wimill.xyz with your domain):

Okta settings

Instance settings UI

In the Instance settings UI, pass the SAML Metadata URL (or content) containing the metadata URL (or XML content).

Okta Metadata URL

Microsoft Entra (Azure)​

In the Azure portal, go to "Enterprise Applications" and create a new one of type "Non-gallery".

Azure Application

Azure Application

Once the application is created, in the application's page go to "Single sign-on" on the left menu, and click on the "SAML" button.

Azure SAML

Edit the configuration to set the Entity ID to windmill and the ACS url to <instance_url>/api/saml/acs.

Azure SAML

Azure SAML

Configuring the NameID claim​

For SAML authentication to work correctly with Entra, you need to configure the primary NameIdentifier claim. In the "Attributes & Claims" section of your SAML configuration:

  1. Click on the NameIdentifier claim to edit it
  2. Set the following values:
    • Name identifier format: Email address
    • Source attribute: user.mail

Entra NameID claim configuration

Configuring the groups claim​

Optional, only needed for login-time group sync. In the "Attributes & Claims" section, click "Add a group claim" and keep "Group ID" as the source attribute. Entra then emits the claim http://schemas.microsoft.com/ws/2008/06/identity/claims/groups with the groups' object ids, which is the same value SCIM stores as the instance groups' external id.

The claim must cover every group SCIM provisions, because a login whose claim names at least one group removes the user from every SCIM-provisioned group the claim does not name. Choose "Groups assigned to the application" when provisioning is scoped to assigned users and groups (see SCIM with Entra); this also keeps the claim below the 150-group limit past which Entra omits it. Choose "Security groups" or "All groups" when provisioning syncs all users and groups. An omitted claim is harmless either way: the login then changes nothing.

Configuring Windmill with the metadata URL​

Once the SAML configuration is complete in Entra, copy the App Federation Metadata URL from the SAML Certificates section:

Azure SAML metadata

Paste this URL in the Windmill Instance settings UI.

Instance settings UI

If for some reasons, the metadata URL cannot be used, you can copy the XML content and paste it in the field instead.

Once it's saved, you can test the login by clicking on the Test button at the bottom, then on the drawer Test sign in.

Azure SAML

SCIM​

Okta​

Configure Okta with the following settings (and replace cf.wimill.xyz with your domain):

warning

The /api/scim endpoint of your windmill instance needs to be exposed to the internet for Okta to push groups/users to your windmill instance.

Okta SCIM

Okta SCIM

Instance settings UI

In the Instance settings UI, choose a random secure string as a SCIM token that you will set in the Okta SCIM connection setting's "Authentication Mode -> HTTP Header".

Okta SCIM

Microsoft Entra (Azure)​

Create an application from the "Enterprise Applications" menu (see Configuring SAML with Microsoft Entra). Once the application is created, in the application's page go to "Provisioning" on the left menu, and click on the "Get started" button.

Azure SCIM

Choose the "Automatic" provisioning mode, and then for the Tenant URL, input the public URL of your Windmill server with the prefix /api/scim.

Azure SAML metadata

Copy the App Federation Metadata URL and paste it in the Instance settings UI.

Instance settings UI

In the Instance settings UI, set the SCIM token containing the secret value that you will share to Azure. You can click "Test" in Windmill's Instance settings UI to validate the SAML metadata URL/Content.

You can then click on the Test Connection button to validate Azure can connect to Windmill's SCIM endpoint. You can then choose to sync only the Users and Groups assigned to this application, or all users and groups. Note that if you choose the former, after you save, go to the application's page and click on the "Users and groups" button in the left menu bar. Only the users and groups present here will be synced to Windmill.

Azure SCIM

Once this is done, you can click on the Save button at the top left. Azure will now synchronize users and groups approximately every 40 minutes.

In Windmill​

Once setup, the groups page should contain a new section:

New section SCIM

Usernames of provisioned users​

The Windmill username (used in u/<username>/ paths, see automatic username creation) is chosen once, when the user is first provisioned. It is the first available of: the username already reserved for that email, the SCIM nickName attribute, the SCIM displayName attribute, and the local part of the email. Characters other than ASCII letters, digits and _ are removed.

To give users their directory login name (for example an Active Directory sAMAccountName such as johsmi) rather than a name derived from their email, map it to nickName in your identity provider:

  • Okta: in the SCIM application, go to Provisioning > To App > attribute mappings and map nickName to appuser.samAccountName (or another expression producing the login name, such as a substring of user.login). Keep the application username format as Email.
  • Microsoft Entra: in the provisioning attribute mappings for users, add a mapping from mailNickname (or an extension attribute holding the sAMAccountName) to nickName.

Existing users keep their username. To change it, rename them from the global users list in the instance settings, which also rewrites their paths.

User deprovisioning​

When your identity provider sends a SCIM PATCH request with active: false for a user, Windmill disables the user at the instance level rather than deleting them. Disabled users:

  • Cannot log in or authenticate via any method
  • Are excluded from on-behalf-of selectors and workspace menus (shown as "user disabled")
  • Retain their workspace memberships and item ownership for auditability

When a user is re-enabled via SCIM (active: true), their access is restored.

A SAML metadata endpoint is also available at GET /api/saml/metadata for identity providers that require it during setup.

Instance groups​

Instance groups are groups shared by every workspace of the instance. Their members can be managed by your identity provider in one of two ways:

  • With SCIM configured, groups from your identity provider are synchronized to Windmill automatically, members included.
  • Without SCIM, superadmins create them by hand and link them to an IdP group, so that SSO logins keep their membership in sync.

Instance groups appear in your Windmill groups interface with a special designation, and can be assigned permissions to folders and resources just like regular groups.

Superadmins manage instance groups from the instance groups page, opened with the "Manage instance groups" button next to the "SSO groups claim" and "SCIM token" instance settings, or from the instance groups section of any workspace's groups page.

Instance-level roles​

Instance groups can be assigned an instance-level role (superadmin or devops) from the instance group editor. When set, all members of the group automatically receive that role. This allows you to manage instance-level access through your identity provider — for example, assigning devops access to an "infrastructure" group or superadmin access to a "platform-admins" group.

Role changes propagate automatically when:

  • A user is added to or removed from the group via SCIM
  • The group's instance role is changed
  • The group is deleted

Manually elevated roles always take precedence — if a superadmin promotes a user manually, group changes won't demote them. For full precedence rules, see Roles and Permissions.

Workspace auto-assignment​

Instance groups can be automatically mapped to workspaces with specific role assignments. This powerful feature allows you to:

  • Automatically add users to workspaces when they join an instance group via SCIM
  • Assign specific roles (admin or any workspace role) to instance group members per workspace
  • Manage multiple instance groups per workspace with different role configurations
  • Track user origin to distinguish between manually added users and those added via instance groups

This mapping is configured in the workspace settings under "User Management" where you can:

  1. Select which instance groups should automatically add users to the workspace
  2. Define the role each instance group's members should receive
  3. View and manage existing auto-assignments

When a user is added to an instance group in your identity provider, they will automatically gain access to all configured workspaces with their assigned roles. Similarly, when users are deleted from the group in the SCIM source, this will automatically propagate to remove them from all mapped workspaces, ensuring consistent access management across your organization.

For more details about how to use instance groups within your workflows and permission structure, see Groups and folders.

Login-time group sync from the IdP groups claim​

SCIM is push-based: a group change in the identity provider reaches Windmill on the provider's next provisioning cycle, about 40 minutes on Entra. For access that has to land faster, such as a break-glass group that grants superadmin, Windmill can also read the groups claim of every SAML or OIDC login and reconcile the user's instance group membership before the session starts. Without SCIM, the groups claim alone can drive instance group membership, revocation included, for groups linked to an IdP group by hand. This is available under Enterprise Edition and is off unless the setting below is set.

How it works​

  • Only instance groups linked to an IdP group take part: those SCIM provisioned and those linked by hand. The claim must carry the same values as the links: group ids for SCIM groups (on Entra, the group object id, the default for both SCIM and the claim), or the ids or full paths you set by hand. Other groups are never touched.
  • Linked groups named in the claim are added and linked groups not named are removed, then the instance-level role and the workspace auto-assignment are re-derived, all before the session token is created. The claim must therefore cover every linked group. A manually granted superadmin or devops role is never revoked.
  • A login whose claim is absent or empty removes the user from every linked group when SCIM is not configured (Keycloak, for example, omits the claim for a user with no groups). With SCIM configured (a SCIM token is set), it changes nothing and logs a warning, leaving removals to SCIM.
  • On Entra, a user in too many groups gets a pointer instead of the claim (groups overage). Such a login changes nothing and logs a warning.
  • Changes apply at the user's next login, not mid-session. A role change also ends the user's other sessions.
  • The setting applies to every SSO client on the instance.

Enabling it​

  1. Have your identity provider emit the groups claim: group ids for SCIM-provisioned groups, or the ids or full paths you link groups to by hand. On Entra, see configuring the groups claim.

  2. In Instance settings -> Authentication -> SSO, set "SSO groups claim" to the attribute name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups for Entra SAML, or the userinfo key (usually groups) for an OIDC provider. Leave it empty to turn the feature off.

    Without SCIM, a wrong attribute name, or a provider that does not send the claim, removes every user from all linked groups at their next login, so check the claim on a real login before relying on it.

  3. Without SCIM, link each instance group to its IdP group.

  4. Give the groups their privileges: an instance-level role from the instance group editor, or a workspace role from the workspace's user management settings.

  5. Test with one user: add them to the group in the identity provider, log in, then remove them and log in again. Grants and removals made at login appear in the audit logs with the "Instance" scope, recorded by the sso user under the operations instance_groups.jit_adduser and instance_groups.jit_removeuser.

Linking an instance group to an IdP group​

A superadmin links an instance group to an IdP group with the "IdP group" field, revealed by "Link to an IdP group" when creating the group or in its editor drawer. The value is the group as the groups claim names it: a group id, or a full path such as /operators/network-team (a user whose claim contains that path also counts as a member of a group linked to /operators). Leave it empty to manage members by hand. Changing or clearing the link does not touch existing members: they follow the new link at their next login, or stay as they are once the link is cleared. Members added by hand to a linked group leave at their next login unless the claim lists them.

Groups provisioned by SCIM show the IdP group read-only.