Skip to main content
Version: current [25.0.x]

External Token Providers Enterprise

You can use a JSON Web Token (JWT) issued by an OpenID Connect (OIDC)-conformant authorization server to establish ODBC/JDBC connections to Dremio. The authorization server can be any JWT provider, including an identity provider (IdP).

External token providers enable client applications to use a JWT issued by an authorization server to authenticate to Dremio. As a result, you can integrate Dremio into client applications without having to provide a long-lived password.

To use this feature, the Dremio administrator or a user with the CONFIGURE SECURITY privilege configures an external token provider in Dremio. This allows Dremio to verify authenticity for external JWTs.

The following figure illustrates the authorization process for a JWT:

This is figure showing an example authorization process for external token providers.

  1. A user accesses the client application that is configured with an IdP for single sign-on (SSO).

  2. The user is redirected to the IdP to log in and authenticate.

  3. The user allows the client application to access Dremio, and the authorization server issues a JWT to the client application for that user.

  4. The client application sends an ODBC/JDBC connection request using the Dremio driver. The connection request includes an empty user name but provides the JWT as the password and sets the property token_type to jwt. See Optional Advanced JDBC Driver Properties for more information.

  5. Dremio's SQL interface sends the JWT to Dremio, and Dremio verifies the JWT's authenticity.

  6. Dremio's SQL interface creates a stateful connection for the user. The client application can use this connection to issue queries on behalf of the user. The connection is closed when the JWT expires. Queries continue to run when the connection is closed. The client application is responsible for refreshing the JWT with the authorization server to extend the Dremio connection.

Benefits of External JWTs​

  • JWTs should be provided by an OIDC-conformant authorization server. OIDC is a commonly used open authentication protocol that extends OAuth 2.0 via an identity layer though which an end user confirms their identity via authentication from their preferred authorization server.
  • You can typically pick your preferred OIDC IdP to generate a JWT.
  • JWTs reduce the threat of security incidents by removing direct access to the JWTs. Typically, JWTs are centrally managed and inaccessible by users.
  • JWTs may be generated with short expiration periods of minutes or hours to make them even more secure.
  • End users do not need to provide long-lived passwords to Dremio, such as user passwords or personal access tokens (PATs).

Understanding the Required Fields for External Token Providers​

The following sections offer additional context for the values required to enable the external token provider feature in Dremio. Each section references the example declaration from the JWT Claims Set of a JWT, as provided by Internet Assigned Numbers Authority (IANA).

tip

Check your authorization server settings or application settings to find the values you need to provide for the required fields for external token providers.

Example JWT Claims Set Declaration
{
"iss": "https://server.example.com",
"preferred_username": "user@dremio.com",
"aud": "https://client.example.org",
"exp": 1440804813
}

Audience​

The audience field identifies the intended recipient or recipients of the JWT and can be application-specific or provider-specific. The audience value must match the aud claim value in the JWT. The JWT Claims Set must include the aud claim. If the aud claim is absent, the JWT is rejected outright.

The aud claim value is an array of case-sensitive strings that consist of StringOrURI values. If the array contains only one value, then the aud claim value will contain only one string. For example, given the aud claim in the example below, the audience field for the external token provider should have the value https://client.example.org:

Single Audience Example
"aud": "https://client.example.org"

The aud claim may also contain multiple comma-separated values as shown in the example below. In this case, the audience field for the external token provider should have the value https://client.example.org,https://client.example2.org:

Multiple Audience Example
"aud": "https://client.example.org,https://client.example2.org"
note

The combination of a given audience and a given issuer should only be used by one external token provider in the system.

For Azure Active Directory, the audience can be the client ID or the resource URI.

User Claim Mapping​

The user claim mapping field identifies the Dremio username of the JWT user. This is considered a private claim name, but it is required from the IdP to identify a user's permissions and access. The JWT Claim Set must include the user claim mapping claim.

The user claim mapping field identifies the key name for the target claim that corresponds to the principal name in the IdP, such as upn. If Dremio is configured to synchronize external group membership, you must specify the correct user claim mapping key name to ensure that Dremio can fetch external users' information based on their Dremio usernames. Otherwise, Dremio's role-based access control (RBAC) may not work as you expect.

For example, in Power BI with Azure Active Directory, the user claim is upn, which is a basic claim in v1.0 access tokens. In this case, the user claim mapping attribute is upn, as shown in the example below:

User Claim Mapping Example
"upn": "user@dremio.com"

If the preferred_username target claim corresponds to usernames in your IdP, not upn, the user claim mapping attribute would be preferred_username instead. For example:

User Claim Mapping Example
"preferred_username": "user@dremio.com"

Issuer URL​

The issuer URL field identifies the principal that issued the JWT, which is typically provider-specific.

The value provided for the issuer URL field must match the iss claim value, which is a case-sensitive string that contains a single StringOrURI value. The JWT Claim Set must include the issuer claim. In the example below, the value for the issuer URL field for the external token provider should be set to https://server.example.com:

Issuer Example
"iss": "https://server.example.com",

JWKS URL​

The JWKS URL is an endpoint that hosts the JWK Set (JWKS), a set of public keys used for verifying the JWT signature. If you do not provide a JWKS URL value when you configure the external token provider in Dremio or with the External Token Provider API, Dremio retrieves the JWKS URL from <issuer>/.well-known/openid-configuration.

Viewing External Token Providers​

To view external token providers:

  1. In the Dremio console, click This is the Settings icon. in the left in the side navigation bar.

  2. In the Settings sidebar, click External Token Providers. The External Token Providers page lists the external token providers configured for Dremio.

Adding an External Token Provider​

Follow the steps in this section to add an external token provider. For more information about the values to provide, read Understanding the Required Fields for External Token Providers.

  1. In the Dremio console, click This is the Settings icon. in the side navigation bar.

  2. In the Settings sidebar, click External Token Providers.

  3. On the External Token Providers page, click Add Provider at the top-right corner.

  4. In the Add Provider dialog, enter the following:

    a. For Name, enter a name for the external token provider.

    b. For Audience, enter the StringorURI value that identifies the intended recipients of the JWT you are adding.

    c. For User Claim Mapping, enter the private claim that maps to the Dremio username.

    d. For Issuer URL, enter the URL for the principal that issued the JWT. Use https with no query or fragment component. Dremio will normalize the issuer URL.

    e. (Optional) For JWKS URL, enter the URL of the IdP's JWKS document. If you do not provide a JWKS URL value, Dremio will retrieve it from {issuerUrl}/.well-known/openid-configuration.

  5. Click Add.

The external token provider is automatically enabled when you add it. To disable it, on the External Token Providers page, toggle the switch in the Enabled column.

If you add multiple external token providers, make sure that they use different issuers and audiences. If multiple external token providers share the same issuer and audience, authentication that uses a JWT with the issuer and the audience will fail, whether the external token providers are enabled or disabled.

Editing an External Token Provider​

Follow the steps in this section to edit an external token provider. For more information about the values to provide, read Understanding the Required Fields for External Token Providers.

  1. In the Dremio console, click This is the Settings icon. in the side navigation bar.

  2. In the Settings sidebar, click External Token Providers.

  3. On the External Token Providers page, find the row for the external token provider you want to edit and click This is the Edit icon. at the right side of the row.

  4. In the Edit Provider dialog, update the values you want to change.

  5. Click Edit.

Deleting an External Token Provider​

To delete an external token provider:

  1. In the Dremio console, click This is the Settings icon. in the side navigation bar.

  2. In the Settings sidebar, click External Token Providers.

  3. On the External Token Providers page, find the row for the external token provider you want to delete and click This is the Delete icon. at the right side of the row.

  4. In the Delete External Provider dialog, click Delete.