# Setting up SSO > Configure Single Sign-On (SSO) for your MotherDuck organization using your identity provider. Single Sign-On (SSO) allows your organization to authenticate MotherDuck users through your existing identity provider (IdP). When SSO is enabled, users with a verified email domain are automatically redirected to your corporate login page, removing the need for separate MotherDuck credentials. :::note SSO is available on **Business** and **Enterprise** plans. ::: ## How SSO works When you configure SSO, MotherDuck connects to your identity provider using either the SAML or OIDC protocol. The login flow works as follows: 1. A user enters their email on the MotherDuck login page. 2. MotherDuck looks up the email domain. If the domain is verified and SSO is enabled, the user is redirected to your corporate IdP. 3. The user authenticates with the IdP. 4. MotherDuck receives the authentication response and creates or updates the user's session. Users with personal email addresses or domains without SSO configured continue to use standard login methods (Google, GitHub, or email and password). The **Sign in with Google** button on the login page is social login, which is not the same as SSO with Google Workspace. See [Google sign-in vs. Google Workspace SSO](#google-sign-in-vs-google-workspace-sso). ## Supported SSO configurations MotherDuck supports four SSO configuration options: | Configuration | Protocol | Use when | | --- | --- | --- | | **Okta** | OIDC | Your organization uses Okta Workforce Identity | | **Microsoft Entra ID** | OIDC | Your organization uses Microsoft Entra ID (formerly Azure AD) | | **SAML** | SAML | Your IdP supports SAML but is not Okta or Entra ID | | **OIDC** | OIDC | Your IdP supports OpenID Connect but is not Okta or Entra ID | The generic SAML and OIDC options allow you to connect any compatible identity provider, such as Google Workspace, PingFederate, or Keycloak. :::note Only Okta and Microsoft Entra ID appear as named options in the setup wizard. Google Workspace is supported through the generic **SAML** option, not a dedicated tile. See [Setting up SSO with Google Workspace](#setting-up-sso-with-google-workspace). ::: ### SAML vs. OIDC **SAML** (Security Assertion Markup Language) is an XML-based protocol widely used in enterprise environments for browser-based SSO. Most traditional enterprise IdPs support SAML. **OIDC** (OpenID Connect) is a JSON-based protocol built on top of OAuth 2.0. It is more common in cloud-native and modern environments. Both protocols achieve the same result: authenticating users through your IdP. Choose the protocol that your IdP supports or that your IT team is most familiar with. ## Prerequisites Before setting up SSO, ensure you have: - Permission to configure SSO in your MotherDuck organization. The Admin preset role includes this permission by default. - A **Business** or **Enterprise** plan - Admin access to your company's identity provider - A **custom domain name** for your organization (for example, `acme.com`) and the ability to add a DNS TXT record to the domain for verification - All users in your organization use **non-aliased email addresses** (addresses like `user+tag@company.com` are not supported) :::caution SSO is supported for organizations where all users belong to a **single MotherDuck organization**. If your users are spread across multiple MotherDuck organizations (for example, separate US and EU orgs), do not enable SSO. Multi-organization SSO support is planned for a future release. ::: ## Setting up SSO ### Step 1: Start SSO configuration in MotherDuck 1. In the MotherDuck UI, click your organization name in the top left and select **Settings**. 2. Navigate to the **Authentication** tab. 3. Click **Set up SSO** to begin the setup process. ![MotherDuck Settings showing the Authentication tab with the Set up SSO button](./img/sso-authentication-settings.png) 4. Select your identity provider from the list, or choose **Custom SAML** or **Custom OIDC** if your IdP is not listed. ![Select your identity provider for SSO configuration](./img/sso-select-identity-provider.png) ### Step 2: Create a MotherDuck application in your identity provider 1. Log in to your identity provider's admin console. 2. Create a new application and name it **MotherDuck**. 3. Select the appropriate protocol (SAML or OIDC) based on your chosen configuration. ### Step 3: Configure the connection The MotherDuck setup wizard provides step-by-step instructions for each provider. Follow the instructions on the SSO onboarding portal to configure the connection between your IDP and MotherDuck. For example, the Okta configuration walks you through creating an OIDC application: ![Okta OIDC SSO configuration wizard showing the Create Application step](./img/sso-okta-create-application.png) ### Step 4: Map user attributes In your IdP, map the following attributes to the MotherDuck application: | Attribute | Required | Description | | --- | --- | --- | | `email` | Yes | The user's email address (primary login identifier) | | `given_name` | No | The user's first name | | `family_name` | No | The user's last name | ### Step 5: Assign users Assign yourself (and optionally other users) to the MotherDuck application in your IdP. ### Step 6: Verify your domain MotherDuck requires domain ownership verification before SSO can be enabled. Follow the instructions to add a DNS TXT record for your domain. Once the record is detected, your domain is verified. ![SSO configuration status showing pending domain verification](./img/sso-pending-domain-verification.png) ### Step 7: Enable SSO After domain verification succeeds, return to the setup wizard and click **Done** to complete the configuration, then click **Enable SSO** to activate the connection. ![SSO configuration dialog to confirm enabling SSO](./img/sso-enable-sso-dialog-confirmation.png) :::warning Enabling SSO is **not reversible** without contacting MotherDuck support. Before enabling, ensure that: - All users in your organization use non-aliased email addresses on the verified domain - Your users belong to **only this** MotherDuck organization - You have tested the IdP configuration by assigning yourself to the application ::: When SSO is enabled: - All existing non-SSO login methods (Google, GitHub, email/password) are **deactivated** for users with the verified domain - Any pending invitations matching the SSO domain will need to **sign up through SSO** - Users must authenticate through the configured IdP going forward ### Step 8: Test SSO login 1. Log out of MotherDuck. 2. On the login page, enter your corporate email address. 3. You should be redirected to your IdP's login page. 4. After authenticating, you are returned to the MotherDuck UI. ## Setting up SSO with Google Workspace Use this when your organization authenticates with Google Workspace and you want MotherDuck logins to go through it. Google Workspace is configured through the generic **SAML** option. Complete the [SSO setup steps](#step-1-start-sso-configuration-in-motherduck) as written, and use the steps below for the Google-side configuration in Step 2 and Step 3. Before starting, ensure you have super administrator access to the Google Admin console, in addition to the [prerequisites](#prerequisites) above. ### Create a custom SAML app in Google 1. In the [Google Admin console](https://admin.google.com), go to **Apps** > **Web and mobile apps**. 2. Click **Add App** > **Add custom SAML app**. 3. Enter `MotherDuck` as the app name, then click **Continue**. ### Exchange metadata with MotherDuck 1. On the **Google Identity Provider details** screen, copy the **SSO URL**, **Entity ID**, and **Certificate**. 2. In the MotherDuck SSO setup wizard, select **SAML** as your identity provider and paste these three values. 3. Copy the **ACS URL** and **Entity ID** that the MotherDuck wizard displays. 4. Back in Google, on the **Service provider details** screen, paste the MotherDuck ACS URL into **ACS URL** and the MotherDuck Entity ID into **Entity ID**. 5. Leave **Start URL** and **Signed response** at their defaults unless the MotherDuck wizard says otherwise. Set **Name ID** to the user's primary email address, since MotherDuck uses email as the login identifier. 6. Click **Continue**. ### Map attributes in Google On the **Attribute mapping** screen, click **Add mapping** for each attribute, then select the **Google Directory attributes** entry on the left and type the **App attributes** name on the right: | Google Directory attribute | App attribute | Required | | --- | --- | --- | | Primary email | `email` | Yes | | First name | `given_name` | No | | Last name | `family_name` | No | Click **Finish**. ### Turn the app on for your users 1. On the MotherDuck app page in the Admin console, click **User access**. 2. Set the service to **On for everyone**, or turn it on for the specific organizational units or groups that should reach MotherDuck. 3. Click **Save**. Google notes that changes can take up to 24 hours to propagate, though they are usually much faster. Return to the MotherDuck wizard to [verify your domain](#step-6-verify-your-domain) and [enable SSO](#step-7-enable-sso). ## Google sign-in vs. Google Workspace SSO MotherDuck offers two distinct ways to authenticate with a Google identity. They are not interchangeable, and mixing them up is the most common problem organizations hit when rolling out SSO. | | **Sign in with Google** button | **Google Workspace SSO** | | --- | --- | --- | | What it is | Social login | SAML SSO through your IdP | | How to use it | Click the Google button on the login page | Type your work email, then continue | | Who controls it | The individual user | Your Google Workspace administrators | | Admin controls | None | Domain verification, JIT provisioning, user assignment | Each method creates a **separate identity**, even when both use the same email address. A user who signs in with the Google button is not the same MotherDuck user as one who authenticates through Google Workspace SSO. :::caution Once SSO is enabled, users must sign in by entering their email address on the login page and clicking **Continue**, which redirects them to Google. ::: Because the identities are separate, a user who clicks the Google button will not be matched to a pending organization invitation. The invitation stays pending, and the user lands in an organization of their own. ### Fixing an account created with the Google button If a user has already signed in with the Google button and cannot reach your organization: 1. Ask the user to log out of MotherDuck completely. 2. [Contact MotherDuck support](/troubleshooting/support/) to remove the social-login identity. This cannot be done from the MotherDuck UI. 3. Once support confirms the identity is removed, have the user return to the login page, enter their work email address, and click **Continue**. They are redirected to Google Workspace and provisioned into your organization. To avoid this for future users, enable [Just-in-Time (JIT) user provisioning](#just-in-time-jit-user-provisioning) so that anyone with a verified domain is provisioned on first login, and consider [adding a MotherDuck tile to your identity provider portal](#adding-a-motherduck-tile-to-your-identity-provider-portal) so users start from Google rather than the MotherDuck login page. ## Just-in-Time (JIT) user provisioning When SSO is enabled, new users from your verified domain can be automatically provisioned on their first login. This is called Just-in-Time (JIT) provisioning. JIT provisioning is enabled by default the first time you activate SSO. Changing this setting requires permission to manage the organization invite policy, which the Admin preset role includes by default. With JIT enabled: - A user enters their corporate email on the MotherDuck login page - They are redirected to your IdP and authenticate - The user is automatically given the option to join your organization at signup ### Controlling access with JIT and invite settings Configuring JIT provisioning requires permission to configure SSO. Changing the organization invite policy requires a separate permission to manage the invite policy. The Admin preset role includes both permissions by default. These two settings work together to control how new users join your organization: | Setting | When enabled | When disabled | | --- | --- | --- | | **JIT provisioning** | Users who authenticate through your IdP can join the organization on first sign-in *(default on first SSO activation)* | New users must be invited by someone with permission to invite members | | **Organization invites** | The invite policy grants members permission to invite others | Only roles that include permission to invite members can invite new users | When both organization invites and JIT provisioning are disabled, new users can only join if someone with permission to invite members invites them. When JIT is enabled but member invitations are disabled, users who have access in your IdP can still join on first sign-in. ![invite policy](./img/org-invite-policy.png) For more information on managing organization members and roles, see [Managing organizations](/docs/key-tasks/managing-organizations/). JIT provisioning handles initial account creation only. It does not manage role changes or account deletion after provisioning. For automated user lifecycle management, see [SCIM provisioning](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/scim/). ### How SCIM affects JIT and invites When SCIM provisioning is enabled, MotherDuck delegates user lifecycle to your IdP. SCIM replaces JIT as the auto-provisioning mode, and organization invites are automatically disabled (the **Invite policy** setting is locked). To re-enable manual invites or fall back to JIT, [disable SCIM](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/scim/#disabling-scim) from the Authentication settings page. :::warning If you disable SCIM and then change members from inside MotherDuck, the user state in MotherDuck and your IdP will drift. Either keep SCIM enabled and manage users in your IdP, or disable SCIM and accept that the two systems are no longer in sync. ::: ## Managing members Managing users with SSO works the same as before. You can invite any new user by supplying their email address. If the email domain matches one of your verified domains, the user will be redirected to their IdP for authentication. :::note **Everyone in an SSO-enabled organization signs in with an email on one of your verified domains.** To give an external collaborator or contractor access, provision a dedicated email address on a verified domain (for example, `contractor-name@yourcompany.com`). Your organization can then manage the account through your IdP. ::: If you have [SCIM provisioning](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/scim/) enabled, manual invites are disabled. Users are created automatically when you assign them to the MotherDuck application in your IdP, and deprovisioned when you unassign them. To hard-delete a user's record from MotherDuck, explicitly delete the user in your IdP — deprovisioning alone keeps the record for later reprovisioning. ## Adding a MotherDuck tile to your identity provider portal If you'd like users to start from your IdP instead of the MotherDuck login page, add a MotherDuck tile to your IdP's app portal. Users click the tile and authenticate through SSO without visiting the MotherDuck login page. 1. In the MotherDuck UI, click your organization name in the top left and select **Settings**. 2. Navigate to the **Authentication** tab. 3. Copy the **IdP-initiated login URL**. It looks like this: ```text https://app.motherduck.com/sso-login/ ``` 4. In your identity provider's admin console, open the MotherDuck application you created and paste the URL as the application's login or tile URL. The field name depends on your provider. For example, in Okta it is **Initiate login URI** under the application's general settings. 5. Save the application, then click the MotherDuck tile in your portal. You should be signed in to MotherDuck through SSO. :::note The tile does not replace the MotherDuck login page. Users can still sign in there with their corporate address. ::: ## Limitations - **Single organization only**: SSO is supported for users who belong to a single MotherDuck organization. Multi-org SSO is planned for a future release. - **No aliased emails**: Email addresses with aliases (for example, `user+tag@company.com`) are not supported when SSO is enabled. - **One connection per domain**: Each verified domain can have only one SSO connection. Users with an email address on that domain in any MotherDuck organization will be redirected to their IdP. - **Non-reversible**: Enabling SSO cannot be undone without contacting [MotherDuck support](mailto:support@motherduck.com). - **CLI and SDK authentication**: Users authenticating through the SDKs continue to use [access tokens](/docs/key-tasks/authenticating-and-connecting-to-motherduck/authenticating-to-motherduck/#authentication-using-an-access-token). SSO applies to browser-based login flows for the WebUI, CLI and MCP. --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fkey-tasks%2Fauthenticating-and-connecting-to-motherduck%2Fauthenticating-to-motherduck%2Fsso-setup%2F&page_title=Setting%20up%20SSO&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.