Version: current [25.0.x]

Configuring SSO Enterprise

This topic describes how to configure Dremio for Single Sign On (SSO) Authentication with an identity provider (IdP) using Azure Active Directory or OpenID.

Azure Active Directory (Azure AD) Authentication
OpenID Authentication

Requirements

To use Azure AD or OpenID, Dremio's webserver must have web server encryption enabled. See the Web Server Encryption section in Configuring Wire Encryption for more information.

Azure Active Directory (Azure AD) Authentication

Setting Up Azure AD

To set up Azure AD:

In Azure AD, navigate to the App registrations section and create a new App registration for the Azure AD instance with your name and the account type.
Click on New Registration.
Complete the Register an application form by adding name, supported account types, and redirect URI of type Web, which is https://<dremio-host>:9047/sso, where <dremio-host> is the hostname or IP address of your Dremio coordinator node.
note
If you are using a load balancer, do not include :9047 in the redirect URI. Instead, configure SSO at the load balancer and use only the load balancer's URL as the redirect URI:
- Load balancer with a default port (80 or 443): https://<load-balancer-URL>/sso
- Load balancer with a non-default port: https://<load-balancer-URL>:<load-balancer-port>/sso
If you are configuring SSO for connections from Tableau, also include either of these redirect URIs:
- If your Dremio cluster does not use encryption: http://<dremio-host>:9047/oauth/callback
- If your Dremio cluster uses encryption: https://<dremio-host>:9047/oauth/callback
Click Save to save the new registration.
Click the app name that you registered to navigate to the app details screen.
Navigate to the Certificates & secrets section, click on New client secret,
Provide a client secret description and expiration, click on Add. Be sure to copy the secret and store it safely as it won't be visible after leaving the page.
In the left navigation menu, click API permissions.
Click Add a permission, and then click Microsoft Graph.
Select Application permissions.
note
Do not click Delegated permissions. The user who is signed in may not have the necessary permissions to make the API calls that Dremio requires to fetch external user/group membership.
Under Select permissions, search for User.Read.All and select the checkbox for the User.Read.All result.
Search again for GroupMember.Read.All and select the checkbox for the GroupMember.Read.All result.
Click Add permissions.
note
The administrator must grant their consent in Azure AD for you to add the User.Read.All and GroupMember.Read.All permissions. If you see a warning in the Status column that the permissions are not granted and the Grant admin consent for <tenant_domain_name> button is grayed out, contact the administrator.
The administrator must log in to the Azure AD account and take the following steps:

1. Navigate to the App registrations section and click the name of the app you registered.

2. In the left navigation menu, click API permissions.

3. Click Grant admin consent for <tenant_domain_name>.
Click Add a permission, and then click Microsoft Graph.
Select Delegated permissions. Under the catalog of OpenID permissions, select openid and profile, which are the minimum required permissions to configure SSO. These permissions should match the scope you configure in the azuread.json file when you configure Dremio for Azure AD.
Click Add permissions. The openid and profile permissions do not require the administrator's consent.
If you are enabling SSO for a Power BI Desktop connection, grant Dremio access to your AAD tenant, if access to it was not already granted.
note
This step is not required if you are using the Dremio Cloud connector from the October 2022 update of Power BI (or a later update).
a. Paste this URL into a web browser, where <tenant-ID> is the tenant ID and <host-url> is the hostname of your Dremio deployment:
```
https://login.microsoftonline.com/<tenant-ID>/v2.0/adminconsent?client_id=429333a8-1521-4502-9101-6d4f2c1de644&scope=User.Read&redirect_uri=<host-url>/sso
```
b. Follow the prompts from Microsoft by signing in with an account that you use to sign into Dremio.
c. In the prompt titled Need admin approval, click "Have an admin account? Sign in with that account" and sign in with an admin account for your AAD tenant.

Configuring Dremio for Azure AD

When configuring Dremio for Azure AD, you modify the dremio.conf and azuread.json files. These modified files must be copied to the /conf directory on all coordinator nodes.

caution

To enable Azure AD support, all coordinator nodes must be configured prior to deploying the Dremio cluster.

To configure Dremio for Azure AD:

Edit the dremio.conf file to include the following configuration.

services.coordinator.web.auth.type: "azuread",
services.coordinator.web.auth.config: "/path/to/azuread.json"

Create an azuread.json file that includes the following properties:
```
{
  "oAuthConfig": {
    "clientId": "<clientId>",
    "clientSecret": "<clientSecret>",
    "redirectUrl": "https://<dremio.host>:9047/sso",
    "authorityUrl": "https://login.microsoftonline.com/<directory.id>/v2.0",
    "scope": "openid profile",
    "jwtClaims": {
      "userName": "preferred_username"
    }
  }
}
```
- clientId: It appears on the Overview screen of your application. This property is also called application ID. A clientId is applicable to the context where you acquire a token using one of the OAuth flows that Azure AD supports. The application ID is same for single application object that corresponds to an application.
- clientSecret: It is the secret that was created in the Setting Up Azure AD section.
- redirectUrl: It is the redirect URI that was created in the Setting Up Azure AD section.
- directory.id: It appears on the Overview screen of your application. This property is also called tenant ID.
note
If you are using a load balancer, do not include :9047 in the redirect URI. Instead, configure SSO at the load balancer and use only the load balancer's URL as the redirect URI:
- Load balancer with a default port (80 or 443): https://<load-balancer-URL>/sso
- Load balancer with a non-default port: https://<load-balancer-URL>:<load-balancer-port>/sso
In Dremio 24+, clientSecret can be encrypted using the dremio-admin encrypt CLI command.
Copy the modified dremio.conf and azuread.json files to every coordinator node in the Dremio cluster.
caution
The LDAP configuration in the dremio.conf and azuread.json files must exist and match on all coordinator nodes.

Using Azure's Managed Storage Identities

Dremio supports using Azure's Managed Storage Identities feature to retrieve the secret when running inside Azure. This feature can be used if you want to avoid storing the secret in plain text.

To set up Azure's Managed Storage Identities:

Enable system-assigned managed identities for the virtual machine instance.
Create an Azure Keyvault and create a new secret. The Azure Key vault asks for a name and the value (which will be the secret generated for the application).
Go to the Access policies section for the Key Vault and add the managed identity for the virtual machine. Make sure that you grant Get permissions for Secrets to the managed identity for the virtual machine.
Change the azuread.json value for clientSecret to the following URI:
```
  ...
  "clientSecret": "azure-vault+https://{keyvault.name}.vault.azure.net/#{secret.name}",
  ...
```
note
This special URI tells Dremio to access the Key Vault located at https://{keyvault.name}.vault.azure.net and load the secret named {secret.name}. The KeyVault value is on the Overview page under DNS Name.

OpenID Authentication

To configure Single Sign On with an Identity Provide over OpenID, perform the following steps:

Edit the dremio.conf file to include the following configuration.

services.coordinator.web.auth.type: "oauth"
services.coordinator.web.auth.config: "/path/to/oauth.json"

Create an oauth.json file with the following properties.

{
  "clientId": "clientId",
  "clientSecret": "clientSecret",
  "redirectUrl": "http://dremioHost:9047/sso",
  "authorityUrl": "authorityUrl",
  "scope": "openid profile email",
  "jwtClaims": {
    "userName": "email"
  },
  "parameters": [
    {"name": "access_type", "value": "offline"},
    ...
  ]
}

The following table describes the oauth.json file properties.

Parameter	Description
clientId	It is based on the OpenID provider.
clientSecret	It is based on the OpenID provider. NOTE: In Dremio 24+, `clientSecret` can be encrypted using the `dremio-admin encrypt` CLI command.
redirectUrl	The URL where Dremio is hosted. The URL must match the redirect url set in the OpenID Provider.
authorityUrl	The location where Dremio can find the OpenID discovery document. For example, Google’s location is `https://accounts.google.com/.well-known/openid-configuration` and the authorityUrl therefore to use is `https://accounts.google.com`, the base location of the well-known directory.
scope	It is based on the OpenID provider. `openid` scope is always required, other scopes can vary by provider.
jwtClaims	Maps fields from the JWT token to fields Dremio requires. The only field currently required is userName, which you should set to the field in JWT that contains the user’s username.
parameters	Optional - any additional parameters required by the OpenID providers.

note

If you are using a load balancer, do not include :9047 in the redirect URI. Instead, configure SSO at the load balancer and use only the load balancer's URL as the redirect URI:

Load balancer with a default port (80 or 443): https://<load-balancer-URL>/sso
Load balancer with a non-default port: https://<load-balancer-URL>:<load-balancer-port>/sso

OIDC Authentication with LDAP Authorization

Dremio supports hybrid OIDC authentication with LDAP authorization (OIDC+LDAP), which allows you to authenticate users with OIDC and fetch user information, groups, and group memberships from LDAP. The way that Dremio authenticates with OIDC and fetches information from LDAP does not change. First, Dremio authenticates users with OIDC. From the OIDC flow, Dremio extracts the username from the ID token. Then, Dremio searches for the username and its group membership in LDAP.

LDAP users cannot log in to Dremio using their LDAP usernames and passwords. Username/password login only works for local users.

Follow these steps to configure OIDC+LDAP. Replace values in angle brackets with the correct values for your organization:

Modify the dremio.conf file to include the following configuration:
Configuration Properties for the dremio.conf File
```
services.coordinator.web.auth.type: "oauth+ldap"
services.coordinator.web.auth.config: "</path/to/config.json>"
```
Create a config.json file in the /conf directory.

Add the oAuthConfig and ldapConfig objects and properties in the config.json file.

note

The properties in the oAuthConfig and ldapConfig objects below are examples. Use the properties that are appropriate for your implementation.

For information about available properties for the oAuthConfig object, see the list of properties under OpenID Authentication.
For information about available properties for the ldapConfig object, see Configuring LDAP.

Example Configuration Properties

{
  "oAuthConfig": {
    "clientId": "<clientId>",
    "clientSecret": "<clientSecret>",
    "redirectUrl": "http://<dremio.host>:9047/sso",
    "authorityUrl": "<Value of the issuer property in the OIDC Discovery Specification>",
    "scope": "openid profile offline_access",
    "jwtClaims": {
      "userName": "<JSON Web Token field that contains the user’s username>"
    }
  },
  "ldapConfig": {
    "connectionMode": "<ANY_SSL | TRUSTED_SSL>",
    "servers": [
      {
        "hostname": "<LDAP host>",
        "port": <LDAP port>
      }
    ],
    "names": {
      "bindDN": "<Distinguished Name for LDAP binding>",
      "bindPassword": "<Password for bindDN>",
      "baseDN": "<Distinguished Name for LDAP base>",
      "userAttributes": {
        "baseDNs": [
          "OU=test,OU=ad,DC=drem,DC=io"
        ],
        "searchScope": "<SUB_TREE | ONE | BASE>",
        "id": "<LDAP user attribute to map as the user's username>",
        "firstname": "<LDAP user attribute to map as first name>",
        "lastname": "<LDAP user attribute to map as last name>",
        "email": "<LDAP user attribute to map as email>"
      },
      "groupDNs": [
        "<Distinguished Name for LDAP group>"
      ],
      "groupMembership": "<memberOf value>",
      "groupFilter": "<LDAP filter for validating groups>",
      "autoAdminFirstUser": <true> | <false>,
      "userGroupRelationship": "<USER_ENTRY_LISTS_GROUPS | GROUP_ENTRY_LISTS_USERS>"
    }
  }
}

Upon successful OIDC authentication, the user's username is established as the value provided for the userName property in the oAuthConfig object in the config.json file. Dremio uses the user's username to query LDAP for the user's group membership information.

In the DN-based approach to configuring OIDC+LDAP, Dremio replaces the placeholder {0} with the user's username. For example:

DN-Based Configuration Example

"userDNs": ["cn={0},dc=staticsecurity,dc=dremio,dc=com"],
"userAttributes": {
    "firstname": "givenName",
    "lastname": "sn",
    "email": "mail"
}

In the attribute-based approach, Dremio looks for the LDAP user whose id value matches the user's username. For example, if you use the following configuration, Dremio looks for the LDAP user whose sAMAccountName matches their username:

Attribute-Based Configuration Example

"userAttributes": {
    "baseDNs": [
        "OU=test,OU=ad,DC=drem,DC=io"
    ],
    "searchScope": "SUB_TREE",
    "id": "sAMAccountName",
    "firstname": "givenName",
    "lastname": "sn",
    "email": "mail"
}

If OIDC authentication and the LDAP search both succeed, Dremio creates a user account with the username. If OIDC authentication is successful but the user's username does not exist in LDAP, the user cannot log in to Dremio.

The LDAP userFilter property works with OIDC+LDAP. You can also use the OIDC application configuration in your identity provider to limit who can authenticate to Dremio.

Administration

Logging in with SSO

When SSO is configured, you are redirected to Azure to login using SSO. Dremio also uses Azure AD for directory services and to look up users and groups.

Backing up with SSO

When using a SSO configuration, you must use personal access tokens (PATs) as the SSO password. See Personal Access Tokens for information on enabling PATs.

$ ./dremio-admin backup -u se3@dremioqa.onmicrosoft.com -d /tmp
  password:
  Backup created at /tmp/dremio_backup_2019-07-17_23.08, dremio tables 32, uploaded files 1

If you use your SSO password instead of your PAT as the password, you will see the following:

$ ./dremio-admin backup -u se3@dremioqa.onmicrosoft.com -d /tmp
password:
Failed to create backup at /tmp:java.io.IOException: Status 500 (Internal Server Error):
Something went wrong (more info: Cannot authenticate users when using Azure AD)

Deleting Users

caution

When deleting users from SSO, ensure that all Personal Access Tokens (PATs) are also deleted.

Configuring SSO Enterprise

Requirements​

Azure Active Directory (Azure AD) Authentication​

Setting Up Azure AD​

Configuring Dremio for Azure AD​

Using Azure's Managed Storage Identities​

OpenID Authentication​

OIDC Authentication with LDAP Authorization​

Administration​

Logging in with SSO​

Backing up with SSO​

Deleting Users​

Additional Information​