docs - user provisioning with SCIM (#48411)

docs/README.md

@@ -152,6 +152,7 @@ Metabase's reference documentation.
   - [SAML with Google](./people-and-groups/saml-google.md)
   - [SAML with Keycloak](./people-and-groups/saml-keycloak.md)
   - [SAML with Okta](./people-and-groups/saml-okta.md)
+- [User provisioning with SCIM](./people-and-groups/user-provisioning.md)
 
 ### Permissions
 

docs/paid-features/overview.md

@@ -11,7 +11,7 @@ Metabase's [Enterprise and Pro](https://www.metabase.com/pricing) plans provide
 - **If you're on Metabase Cloud**, your Pro/Enterprise features will activate automatically.
 - **If you're self-hosting,** you'll need to [activate your license](./activating-the-enterprise-edition.md).
 
-## Authentication
+## Authentication and provisioning
 
 Pro and Enterprise plans include more ways to authenticate people and manage groups.
 
@@ -23,6 +23,7 @@ Pro and Enterprise plans include more ways to authenticate people and manage gro
   - [Setting up SAML with Okta](../people-and-groups/saml-okta.md)
 - [Authenticating with JWT](../people-and-groups/authenticating-with-jwt.md)
 - [Multiple domains with Google Sign-in](../people-and-groups/google-and-ldap.md#multiple-domains-for-google-sign-in)
+- [User provisioning with SCIM](../people-and-groups/user-provisioning.md)
 
 ## Permissions
 
@@ -91,7 +92,7 @@ All Metabase editions include global caching controls. Pro and Enterprise plans
 
 See how people are using your Metabase.
 
-- [Metabase analytics](../usage-and-performance-tools/usage-analytics.md)
+- [Usage analytics](../usage-and-performance-tools/usage-analytics.md)
 
 ## Admin tools
 

docs/people-and-groups/authenticating-with-saml.md

@@ -10,6 +10,7 @@ redirect_from:
 
 Integrating your SSO with Metabase allows you to:
 
+- Provision a Metabase account when someone logs in to Metabase.
 - Automatically pass user attributes from your SSO to Metabase in order to power [data sandboxes](../permissions/data-sandboxes.md).
 - Let people access Metabase without re-authenticating.
 
@@ -19,7 +20,7 @@ Before setting up SAML, make sure you know the password for your Metabase admin
 
 ## Setting up SAML with your IdP in Metabase
 
-Once you've [confirmed the password to your Metabase admin account](#confirm-the-password-for-your-metabase-admin-account), head over to the **Settings** section of the Admin Panel, then click on the **Authentication** tab. Click the **Configure** button in the SAML section of the Authentication page, and you'll see this form:
+Once you've [confirmed the password to your Metabase admin account](#confirm-the-password-for-your-metabase-admin-account), head over to the **Settings** section of the Admin Panel, then click on the **Authentication** tab. Click the **Set up** button in the SAML section of the Authentication page, and you'll see this form:
 
 ![SAML form](images/saml-form.png)
 
@@ -29,6 +30,8 @@ The form includes three sections:
 2. [IdP info that you'll need to tell Metabase about](#enabling-saml-authentication-in-metabase).
 3. [Signing SSO requests (optional)](#settings-for-signing-sso-requests-optional).
 
+## SAML guides
+
 First you'll need to make sure things are configured correctly with your IdP. Each IdP handles SAML setup differently.
 
 We've written up some guides for the most common providers:
@@ -45,6 +48,12 @@ If you don't see your IdP listed here:
 - Using the information found on the Metabase SAML form, fill out your IdP's SAML form.
 - For more information, see the next section on [Generic SAML configuration](#generic-saml-configuration).
 
+## User provisioning
+
+By default, Metabase will create accounts for people who don't yet have a Metabase account but who are able to log in via SAML SSO.
+
+If you've set up [User provisioning with SCIM](./user-provisioning.md), you'll want to turn this setting off so that Metabase doesn't automatically create a new account for anyone who authenticates successfully, as you may want to use SCIM to determine who can and can't create an account in Metabase.
+
 ## Generic SAML configuration
 
 The top portion of the SAML form in Metabase has the information you'll need to fill out your IdP's SAML form, with buttons to make copying the information easy.

docs/people-and-groups/saml-azure.md

@@ -57,3 +57,7 @@ Under "Tell Metabase about your identity provider", enter the following:
 - **SAML Identity Provider Issuer**: the "Microsoft Entra Identifier" URL you got from the Microsoft Entra ID SAML SSO configuration.
 
 Click on **Save Changes** below, and you should now be able to log in via Microsoft Entra ID.
+
+## Further reading
+
+- [User provisioning](./user-provisioning.md)
\ No newline at end of file

docs/people-and-groups/saml-okta.md

@@ -199,3 +199,7 @@ For common issues, go to [Troubleshooting SAML][troubleshooting-saml].
 [saml-doc]: ./authenticating-with-saml.md
 [site-url]: ../configuring-metabase/settings.md#site-url
 [troubleshooting-saml]: ../troubleshooting-guide/saml.md
+
+## Further reading
+
+- [User provisioning](./user-provisioning.md)
\ No newline at end of file

docs/people-and-groups/start.md

@@ -67,6 +67,10 @@ Create keys to authenticate API calls.
 [saml-keycloak]: ./saml-keycloak.md
 [sso-def]: https://www.metabase.com/glossary/sso
 
+## [User provisioning](./user-provisioning.md)
+
+Metabase supports user provisioning via the SCIM protocol.
+
 ## [Accessibility](./accessibility.md)
 
 Notes on Metabase's accessibility.

docs/people-and-groups/user-provisioning.md

+---
+title: User provisioning with SCIM
+---
+
+# User provisioning with SCIM
+
+{% include plans-blockquote.html feature="User provisioning with SCIM" %}
+
+Metabase supports user provisioning via the System for Cross-domain Identity Management (SCIM) protocol. In addition to Single Sign-on (SSO), you can set up user provisioning in Metabase with SCIM to:
+
+- **Decouple authentication from provisioning**. Even though anyone could authenticate with SSO, you may only want some people to be able to create an account in Metabase.
+- **Support deprovisioning user accounts**. If you deactivate someone from your SSO, SCIM can let Metabase know to deactivate their Metabase account as well.
+
+> For now, Metabase officially supports SCIM for [Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm?cshid=ext_Apps_App_Integration_Wizard-scim) and [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal). Other SCIM providers may work, but we haven't tested them. If you're having issues with another identity provider, please [reach out to us](https://www.metabase.com/help/premium).
+
+## Setting up user provisioning
+
+![Setting up user provisioning with SCIM in Metabase](./images/user-provisioning.png)
+
+To set up user provisioning. Click on the settings **Gear** icon in the upper right and navigate to **Admin settings** > **Settings**> **Authentication**.
+
+Click on the **User provisioning** tab.
+
+## User provisioning via SCIM
+
+To set up user provisioning with SCIM, hit the toggle to enable it. Metabase will tell you the SCIM endpoint URL and SCIM token to share with your identity provider.
+
+> If you've previously set up user provisioning with SAML, Metabase will turn that setting off and use the SCIM setup instead.
+
+## SCIM endpoint URL
+
+The SCIM endpoint is `/api/ee/scim/v2`. So your URL will looks something like:
+
+```
+https://metabase.example.com/api/ee/scim/v2
+```
+
+Replacing the hostname with your Metabase's hostname.
+
+Share this endpoint URL with your identity provider.
+
+## SCIM token
+
+Copy the token and save the token somewhere safe. For security, Metabase can't show you the token again. You can, however, regenerate the token, but you'll need to let your identity provider know about the new token.
+
+## SCIM with Okta
+
+Once you've enabled SCIM in Metabase and gotten your SCIM endpoint URL and SCIM token, follow the docs for [Setting up SCIM in Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm?cshid=ext_Apps_App_Integration_Wizard-scim).
+
+With Okta, Metabase supports user and group provisioning; groups are created and populated in Metabase.
+
+## SCIM with Microsoft Entra ID
+
+Once you've enabled SCIM in Metabase and gotten your SCIM endpoint URL and SCIM token, follow the docs for [Setting up SCIM in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/configure-automatic-user-provisioning-portal).
+
+With Microsoft Entra ID, Metabase only supports user provisioning (groups aren't created or populated).
+
+## Notify admins of new users provisioned from SSO
+
+If you're not using SCIM to provision user accounts, you can optionally have Metabase send an email to admins whenever someone signs in to Metabase via SSO for the first time (which creates a Metabase account). This setting doesn't require you to set up SCIM.
+
+## Further reading
+
+- [Authenticating with SAML](./authenticating-with-saml.md)
+- [SAML with Okta](./saml-okta.md)
+- [SAML with Microsoft Entra ID](./saml-azure.md)