---
sidebar_position: 2
title: Setting up SSO
description: Configure Single Sign-On (SSO) for your MotherDuck organization using your identity provider.
---

import VideoPlayer from '@site/src/components/VideoPlayer';

# Setting up SSO

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.
:::

<VideoPlayer
    playbackId="RYGDnxGGFq018WBK00ALztL4KsGfG5BxzLXsiFHVczPFk"
    title="SSO Setup Walkthrough"
    autoPlay="true"
    muted="true"
    loop="true"
/>

## 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).

## 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.

### 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:

- **Org Admin** role in your MotherDuck organization
- 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.

## 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.

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

Admins can configure JIT provisioning and organization invite policies from the organization **Settings** page. 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 login | New users must be invited by an Admin |
| **Organization invites** | Any member can invite new users to the organization | Only Admins can invite new users, giving you tighter control over who has access |

When both organization invites and JIT provisioning are disabled, new users can only join if an Admin invites them. When JIT is enabled but invites are disabled, users who have been given access in your IdP can still join on first login, but members cannot send invitations.

![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, SCIM provisioning support is planned for a future release.

## 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.


## 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.