diff --git a/docs/docs/administration-and-security/access-control/index.md b/docs/docs/administration-and-security/access-control/index.md index 088e6b5426d6..879a696c7b50 100644 --- a/docs/docs/administration-and-security/access-control/index.md +++ b/docs/docs/administration-and-security/access-control/index.md @@ -24,6 +24,7 @@ Using the following authentication methods requires an [Enterprise subscription] - [SAML](/administration-and-security/access-control/saml) - [Active Directory (LDAP)](/administration-and-security/access-control/ldap) - [Microsoft ADFS](/administration-and-security/access-control/adfs) +- [SCIM provisioning](/administration-and-security/access-control/scim) Please get in touch in order to integrate with LDAP or ADFS. @@ -47,10 +48,10 @@ If you are self-hosting Flagsmith, you can restrict authentication methods per e ## Disabling password authentication {#disable-password} -If you are self-hosting Flagsmith, you can disable password authentication by setting the `PREVENT_EMAIL_PASSWORD` +If you are self-hosting Flagsmith, you can disable password authentication by setting the `PREVENT_EMAIL_PASSWORD` environment variable on the Flagsmith API. This will also hide the username and password fields from the login screen. Note that this does not disable password authentication for [Django Admin](/deployment-self-hosting/administration-and-maintenance/using-the-django-admin#email-and-password). -If you have a private cloud Flagsmith instance, contact Flagsmith support to disable password authentication once -you have successfully set up an alternative authentication method. +If you have a private cloud Flagsmith instance, contact Flagsmith support to disable password authentication once you +have successfully set up an alternative authentication method. diff --git a/docs/docs/administration-and-security/access-control/scim.md b/docs/docs/administration-and-security/access-control/scim.md new file mode 100644 index 000000000000..cc2c865a08fa --- /dev/null +++ b/docs/docs/administration-and-security/access-control/scim.md @@ -0,0 +1,181 @@ +--- +title: SCIM provisioning +sidebar_label: SCIM +sidebar_position: 15 +--- + +:::info + +SCIM provisioning requires an [Enterprise subscription](https://flagsmith.com/pricing). + +::: + +SCIM (System for Cross-domain Identity Management) is a standard protocol for automating user and group provisioning +between your identity provider and Flagsmith. It lets your identity provider push changes to Flagsmith automatically, so +you do not need to manage users manually or wait for them to log in. + +With SCIM, you can: + +- Create Flagsmith users ahead of their first login, so they already have the right group memberships and permissions + waiting for them. +- Remove users from your Flagsmith organisation when they are deprovisioned in your identity provider +- Sync group membership so that adding or removing a user from a group in your identity provider is reflected in + Flagsmith automatically. + +SCIM works alongside your existing SSO configuration. SSO handles authentication (how users log in), while SCIM handles +provisioning (which users and groups exist in Flagsmith, and who belongs to what). + +## Prerequisites + +- Your Flagsmith organisation must have an active Enterprise licence. +- You must have an SSO configuration (such as [SAML](/administration-and-security/access-control/saml)) set up for your + organisation. SCIM manages the user and group lifecycle, but users still authenticate through your SSO provider. + +## User lifecycle + +When your identity provider provisions a user through SCIM: + +1. If the user does not exist in Flagsmith, they are created with the email, first name and last name from the SCIM + request. They are added to the organisation as a regular user. +2. If the user already exists (matched by email, case-insensitive), they are added to the organisation if they are not + already a member. + +When your identity provider deprovisions a user (sets `active` to `false` or sends a DELETE request): + +1. The user is removed from the organisation in Flagsmith. This also removes all their project and environment + permissions within that organisation, and removes them from all + [permission groups](/administration-and-security/access-control/rbac#groups) in that organisation. +2. The user's data (audit log entries, change request history) is preserved. + +## Group lifecycle + +SCIM groups map to Flagsmith [permission groups](/administration-and-security/access-control/rbac#groups) within the +organisation. Groups are matched by the `externalId` field in the SCIM request, which corresponds to the "External ID" +field on Flagsmith permission groups — the same field used by +[SAML group sync](/administration-and-security/access-control/saml#using-groups-from-your-saml-idp). + +When your identity provider creates or updates a group through SCIM: + +1. If no Flagsmith permission group with a matching external ID exists in the organisation, one is created with the + display name and external ID from the SCIM request. +2. Group membership is synced to match the SCIM request: users are added or removed as needed. + +When your identity provider deletes a group through SCIM: + +1. All users are removed from the group. +2. The group is deleted from the organisation. + +### Interaction with SAML group sync + +If you have [SAML group sync](/administration-and-security/access-control/saml#using-groups-from-your-saml-idp) +configured, both SCIM and SAML will manage group membership. SCIM changes are applied as they arrive from your identity +provider. SAML group sync is applied at login time. The two mechanisms are complementary: SCIM keeps groups current +between logins, while SAML group sync acts as a reconciliation point at each login. + +## Setup + +### 1. Create a SCIM configuration + +From the Flagsmith dashboard, go to **Organisation Settings** > **SSO** > **SCIM**. + +Click "Create SCIM Configuration". This generates a SCIM bearer token. Copy this token and store it securely. It is +shown only once and cannot be retrieved later. If you lose it, you can regenerate a new token from the same page. + +### 2. Configure your identity provider + +Add Flagsmith as a SCIM application in your identity provider. You will need: + +- **SCIM base URL**: `https://flagsmith.example.com/api/v1/scim/v2/`, replacing `flagsmith.example.com` with your + Flagsmith API domain. On Flagsmith SaaS, this is `https://api.flagsmith.com/api/v1/scim/v2/`. +- **Bearer token**: the token you copied in the previous step. + +The exact steps depend on your identity provider. See the guides below for common providers. + +### 3. Assign users and groups + +In your identity provider, assign users and groups to the Flagsmith SCIM application. Your identity provider will begin +pushing these to Flagsmith immediately. + +## Identity provider guides + +:::note + +These guides were last verified in April 2026. If your identity provider's UI has changed, refer to their documentation +for the most up-to-date steps. + +::: + +### Okta + +1. Open the Flagsmith application in the Okta admin dashboard. +2. Go to the "General" tab and click "Edit" under "App Settings". +3. Enable "SCIM provisioning" and click "Save". +4. A new "Provisioning" tab will appear. Open it and click "Edit" under "SCIM Connection". +5. Set the SCIM connector base URL to your Flagsmith SCIM base URL. +6. Set the unique identifier field to `email`. +7. Under "Supported provisioning actions", enable: Push New Users, Push Profile Updates, and Push Groups. +8. Set the authentication mode to "HTTP Header" and paste your SCIM bearer token. +9. Click "Test Connector Configuration" to verify the connection, then save. +10. Still on the "Provisioning" tab, under "To App", enable: Create Users, Update User Attributes, and Deactivate Users. + +### Microsoft Entra ID (Azure AD) + +1. In the Entra admin centre, go to Enterprise Applications and find your Flagsmith application. +2. Go to "Provisioning" and click "Get started". +3. Set the provisioning mode to "Automatic". +4. Under "Admin Credentials", set the tenant URL to your Flagsmith SCIM base URL and the secret token to your SCIM + bearer token. +5. Click "Test Connection" to verify, then save. +6. Under "Mappings", configure the user and group attribute mappings. Ensure `emails[type eq "work"].value` maps to the + user's email address. +7. Set the provisioning status to "On" and save. + +### OneLogin + +1. In the OneLogin admin panel, go to Applications and find your Flagsmith application. +2. Go to "Configuration" and set the SCIM base URL and SCIM bearer token. +3. Go to "Provisioning" and enable provisioning. +4. Under "Entitlements", configure which users and groups should be pushed to Flagsmith. + +## SCIM API + +Flagsmith implements a SCIM 2.0 API (RFC 7643, RFC 7644) with endpoints for managing users, groups, and discovering +service provider capabilities. The full API specification is available in the +[Swagger documentation](https://api.flagsmith.com/api/v1/docs/). + +All SCIM endpoints are under `/api/v1/scim/v2/` and require a valid SCIM bearer token in the `Authorization` header. The +API supports filtering (e.g. `filter=userName eq "user@example.com"`) and pagination (`startIndex`, `count`) on list +endpoints as defined by the SCIM 2.0 specification. + +## Managing SCIM tokens + +You can view and manage SCIM configurations from **Organisation Settings** > **SSO** > **SCIM**. From this page you can: + +- Regenerate a SCIM token. This invalidates the previous token immediately. +- Delete the SCIM configuration. This stops all SCIM provisioning for the organisation. Existing users and groups are + not removed. + +## Troubleshooting + +### Users are not being provisioned + +- Verify the SCIM base URL ends with `/api/v1/scim/v2/` (including the trailing slash). +- Verify the bearer token is correct. If in doubt, regenerate it. +- Check that the user's email address is included in the SCIM request. Flagsmith requires an email to create a user. + +### Users are provisioned but cannot log in + +- SCIM only manages the user lifecycle (creating accounts, setting group membership). Users still need to authenticate + through your SSO provider. Verify that your SAML configuration is set up correctly. + +### Group membership is not syncing + +- Verify that the `externalId` in the SCIM group request matches the "External ID" on the corresponding Flagsmith + permission group. If the group was created by SCIM, this is set automatically. +- If you are also using SAML group sync, note that SAML will re-sync group membership at each login. The two mechanisms + are designed to work together, but if they use different group identifiers, they may conflict. + +### Deprovisioned users still appear in the organisation + +- Check that your identity provider is sending a PATCH request with `active` set to `false`, or a DELETE request, when + deprovisioning a user. Some identity providers require explicit configuration to send deprovisioning events.