Adding an SSO application for dbt Enterprise

1.The values dbt hands to your identity provider

With single sign-on, your identity provider (IdP) decides who can log in to dbt, not dbt itself. Group-based access in dbt is built on top of it. SSO is a feature of dbt Enterprise-tier plans. Any SAML 2.0-compliant IdP works, and Okta, Microsoft Entra ID, Google Workspace and OneLogin each have their own dedicated setup. Every setup follows the same pattern. You create an application in the IdP using values dbt gives you, then paste the values the IdP generates back into dbt.

All of dbt's values are on one screen. Open Account settings, click SSO & SCIM, click Get started (or Edit if SSO is already configured) and choose your IdP in the Provider type dropdown. The Auth0 URI and Auth0 Entity ID for your region then appear under Identity provider values. Keep this screen open beside the IdP's form while you fill it in.

The callback host is not your account URL. Authentication for every region and account goes through Auth0, so the single sign-on URL always starts with the Auth0 URI, for example auth.cloud.getdbt.com. If an administrator swaps in the account prefix because it looks more specific, the callback breaks. dbt identifies your account by a different value: the login URL slug.

dbt generates the slug automatically, and you can't change it. It contains only letters, numbers and dashes and is unique across all dbt accounts, for example dbt-labs-afk123. A SAML configuration uses it three times: as the connection parameter on the callback URL, at the end of the audience URI (urn:auth0:<YOUR_AUTH0_ENTITYID>:<login URL slug>), and on its own as the Relay State. The slug also forms your enterprise login URL, which is the URL IdP-initiated sign-ins use.

Sources1

2.Creating a SAML 2.0 application in Okta, OneLogin or a generic IdP

Every IdP creates a SAML application the same way: platform Web, sign-on method SAML 2.0, app name dbt. What changes between providers is the field labels, not what the fields mean. Okta's Single sign on URL is OneLogin's ACS (Consumer) URL, and Okta's Audience URI (SP Entity ID) is OneLogin's Audience (EntityID). The supported SSO features are IdP-initiated SSO, SP-initiated SSO and just-in-time provisioning.

Relay State is easy to overlook because some IdPs label it optional. dbt's SSO configuration requires it. Set it to your login URL slug.

Next come the attributes. dbt expects email, first_name and last_name, plus a NameID. NameID needs the most care. An email address works as NameID, but if that address ever changes, dbt creates an entirely new user. Use an identifier that never changes instead: ID in a generic IdP, OneLogin ID in OneLogin. In OneLogin, also check Include in SAML assertion for every parameter, and match the casing exactly.

The groups attribute is what makes the app useful beyond the login screen. dbt's role-based access control places users in dbt groups based on group mappings from the IdP, so the IdP must send an attribute named groups. The Okta example sends every group (Matches regex .*), but a narrower filter is often better. If all your dbt groups share a prefix, a filter like Starts With: DBT_CLOUD_ sends only those groups. In Okta that narrowing can be required: Okta returns only 100 groups per user, so users in more than 100 IdP groups need a more restrictive filter.

Okta's Application username depends on whether you will use SCIM. For SSO alone, use a stable value such as user.getInternalProperty("id"). If you plan to add SCIM provisioning, choose Email format instead, because SCIM requires the username to be an email address that matches the email attribute.

Sources12

3.Registering a Microsoft Entra ID application

Microsoft Entra ID (formerly Azure AD) can be connected in two ways. The dedicated dbt setup starts in App registrations and takes a Client ID and Client Secret back to dbt; a SAML route through an Enterprise application is covered further down. For the app-registration route, the first decision is Supported account types. It controls which Entra tenants can use the app (your dbt tenancy plays no part in this). It also fixes what you will later enter in dbt's Microsoft Entra ID Domain field. Most enterprises should register a single-tenant app. A multi-tenant app also needs an administrator in each tenant to grant consent. Until they do, users from that tenant see an "admin approval required" screen.

The redirect URI is the Auth0 callback, https://YOUR_AUTH0_URI/login/callback, for both single-tenant and multi-tenant apps. Two things must be right: the value, and the platform type. Choose Web, not Single-page application (SPA). dbt redeems the authorization code on the server using the client secret. If the redirect URI is registered under SPA, Entra ID enforces PKCE and rejects that exchange, and sign-in fails with AADSTS9002325.

Next, give the app permission to read groups. Under API permissions, add the delegated Microsoft Graph permissions User.Read and GroupMember.Read.All, then click Grant admin consent. You may also need Directory.Read.All, but only for users assigned to more than 200 groups. Group count has a second limit. Azure emits at most 150 groups in the SSO token, and a user in more groups than that appears to belong to none. To avoid this, assign groups to the dbt app and set a group claim, so Azure emits only the groups dbt needs.

Under Enterprise applications, assign the users and groups who should have access, and set User assignment required? to Yes. If it is set to No, anyone with a direct link to the app can open it. dbt matches people by their User principal name (UPN), which is usually formatted as an email address. Finally, create a client secret (730 days is the recommended expiry) and record three values: the Application (client) ID, the Directory (tenant) ID and the secret's value.

Back in dbt, set Log in with to Microsoft Entra ID Single Tenant or Multi Tenant, then paste the Client ID and Client Secret. The secret must be the Secret Value, not the Secret ID. The Tenant ID field appears only for single tenant. Fill Microsoft Entra ID Domain with your primary domain, or with the authority string for a multi-tenant app.

The SAML route builds the app as an Enterprise application instead. Choose Enterprise applications, + New application, Create your own application, and select Integrate any other application you don't find in the gallery (Non-gallery). Under Single sign-on, pick SAML and edit the Basic SAML Configuration: the Identifier (Entity ID) is urn:auth0:<YOUR_AUTH0_ENTITYID>:<login URL slug>, the Reply URL (Assertion Consumer Service URL) is https://YOUR_AUTH0_URI/login/callback?connection=<login URL slug>, and Relay State is the login URL slug. In User Attributes & Claims, set the Unique User Identifier (Name ID) format to Unspecified with source attribute user.objectid, and add claims email (user.mail), first_name (user.givenname) and last_name (user.surname). For groups, add a group claim with source attribute Group ID and customize its name to groups. The Group ID is the group's GUID and must be lowercase for mappings to work. In dbt, the Identity Provider SSO URL is Entra's Login URL and the Identity Provider Issuer is the Microsoft Entra Identifier.

Sources31

4.Connecting Google Workspace through an OAuth client

Google Workspace (shown as GSuite in dbt's form) can be connected through an OAuth client or through a custom SAML app. The OAuth route has dbt authenticate GSuite users with a Client ID and Client Secret that you create in a GCP project. The person doing the setup needs permission to create Google OAuth2 applications and to enable the Google Admin SDK. Supported features for this integration are SP-initiated SSO and just-in-time provisioning.

The Google side has three parts:

1. Configure the OAuth consent screen with Application type internal, application name dbt and the default scopes email, profile, openid. 2. Create an OAuth Client ID of type Web application. Set Authorized Javascript origins to https://YOUR_ACCESS_URL and Authorized Redirect URIs to https://YOUR_AUTH0_URI/login/callback, which uses two different hosts, then record the Client ID and Client Secret. 3. Enable the Admin SDK for the project. dbt needs it to request group membership from the GSuite API.

The two hosts mean different things. The Access URL is your account's own dbt URL for your region and plan, the kind of account-specific address such as ks123.us1.dbt.com, and you take it from your account settings. The Auth0 URI is the shared authentication host from the SSO & SCIM screen, the same one every other IdP uses for its callback. The Access URL also appears in the enterprise login URL, https://YOUR_ACCESS_URL/enterprise-login/LOGIN-SLUG.

In dbt, set Log in with to GSuite, paste the Client ID and Client Secret, and fill in Domain in GSuite. That field acts as a gate: only users with an email address in the listed domain can sign in through GSuite. If you need more than one domain, enter them as comma-separated values (CSV), such as dbtlabs.com, fishtowndata.com. Save & Authorize puts you through the OAuth flow yourself. Afterwards, check that the Credentials page shows a groups entry listing your GSuite groups. If it doesn't, group-based access will have nothing to map, so fix that before inviting anyone.

The alternative is a custom SAML app in the Google Admin Console, opened as a super administrator under Apps, Web and mobile apps, Add custom SAML app. Download the IdP metadata and copy the SSO URL, Entity ID and certificate. On Service Provider Details, set the ACS URL to https://YOUR_AUTH0_URI/login/callback?connection=<login URL slug>, the Audience URI (SP Entity ID) to urn:auth0:<YOUR_AUTH0_ENTITYID>:<login URL slug> and the Start URL to the login URL slug, then select Signed response. The default Name ID is the primary email; a stable value that survives email changes is better if you have one. To use role-based access control, map the Google groups to a groups app attribute in the Group membership field.

Sources41

5.Saving, testing and maintaining the connection

For SAML IdPs, finishing in dbt means copying three values across. Set Log in with to your provider, then paste the Identity Provider SSO Url, the Identity Provider Issuer and the X.509 Certificate in PEM format, and click Save. To test, open the enterprise login URL, https://YOUR_ACCESS_URL/enterprise-login/LOGIN-SLUG. Users assigned to the app can also launch dbt from the IdP directly. For most users, the recommended entry point is https://login.dbt.com, which lists every account they can access across instances. Account administrators can turn that discovery on or off with Enable global account discovery.

Credentials expire. When an Okta certificate or an Entra ID client secret expires, an IdP admin has to generate a new one and paste it into dbt, or users lose access.

The Entra ID configuration has two group options below the credential fields. Include all groups, on by default, also returns the parent groups of nested memberships. Maximum number of groups to retrieve defaults to 250, and you can raise it. SSO configurations created before December 2025 may still request Directory.Read.All. To move to the narrower scopes, delete the configuration and re-create it.

One Entra failure is hard to diagnose. Users complete the Microsoft login and land on dbt's generic "Server error!" page. The usual cause is AADSTS500031: Entra ID cannot find a SAML signing certificate for the application. The certificate belongs to the application's SAML single sign-on settings under Enterprise applications, so check there even if the connection was built from an app registration with a client secret. The error appears only in the Enterprise application's Sign-in logs, filtered by Failure status. Add the certificate under SAML Signing Certificate. If the existing certificate is corrupted, create a new one, mark it Active, and remove the old one.

With sign-in working, the next steps are to map IdP groups to [RBAC groups](lesson:5.6) and, if you use them, to [license mappings](lesson:5.3). Okta and Entra ID can also add SCIM to automate user and group provisioning.

Sources23

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.The IdP's single sign-on URL should use your account's cell-specific URL, such as ks123.us1.dbt.com.Why is that wrong?

   The callback always uses the shared Auth0 URI, because dbt authenticates every region and account through Auth0.

   Covered in The values dbt hands to your identity provider

2. 2.Relay State can be left blank when the IdP marks it as optional.Why is that wrong?

   dbt's SSO configuration requires Relay State, set to the login URL slug, whatever the IdP's form says.

   Covered in Creating a SAML 2.0 application in Okta, OneLogin or a generic IdP

3. 3.Email address is the best NameID because it is human-readable.Why is that wrong?

   Email works as NameID, but an email change makes dbt create a brand-new user. Use an identifier that never changes.

   Covered in Creating a SAML 2.0 application in Okta, OneLogin or a generic IdP

4. 4.Sending every Okta group with a catch-all filter always works, however many groups a user has.Why is that wrong?

   Okta returns at most 100 groups per user, so users in more groups need a more restrictive filter such as Starts With: DBT_CLOUD_.

   Covered in Creating a SAML 2.0 application in Okta, OneLogin or a generic IdP

5. 5.Paste the client secret's ID into dbt's Client Secret field.Why is that wrong?

   dbt needs the secret's value, which is shown once when the secret is created, not the Secret ID.

   Covered in Registering a Microsoft Entra ID application

6. 6.A user in hundreds of Entra ID groups simply gets their first 150 groups mapped in dbt.Why is that wrong?

   Above the 150-group token cap, the user appears to belong to no groups at all. Scope the group claim to the dbt app's groups.

   Covered in Registering a Microsoft Entra ID application

7. 7.The Google OAuth consent screen can use any application type.Why is that wrong?

   The consent screen is configured with Application type internal.

   Covered in Connecting Google Workspace through an OAuth client