External Token Providers Enterprise

External token providers are OIDC identity providers that issue JSON Web Token (JWT) when a user authenticates using an application client. After receiving a JWT from the external token provider, the client application uses Dremio token exchange to obtain an OAuth access token used to create connections to Dremio.

The OIDC external token provider does not need to be the same identity provider used by the Dremio console for SSO. The provider requires an application registration specifying the OAuth authorization flow to be used between the external token provider and the client to obtain the JWT that will be sent to Dremio.

This page outlines the steps for configuring an external token provider so Dremio can interpret and validate the JWTs issued by your provider.

JSON Web Tokens (JWT)

A JSON web token (JWT) is an open standard that defines a compact and self-contained way for securely transmitting information as a JSON object. JWTs are trusted because they are digitally signed using a secret or key pair. Hence, the information they contain has not been modified. JWTs may be generated with short expiration periods of minutes or hours to reduce the threat of a lost or compromised token.

The OIDC specification describes the content of the JWT and the authorization process. Claims in a JWT contain information asserted about a subject. They are key/value pairs in which the key is a string, and the value can be any JSON type (a string, a number, a boolean, an array, or a JSON object).

Example: External JWT Claims from Microsoft Entra ID

{
  "aud": "0853fce0-c748-4c54-aa58-f5b9af279840",
  "iss": "https://login.microsoftonline.com/3e334762-b0c6-4c36-9faf-93800f0d6c71/v2.0",
  "upn ": "gnarly@dremio.com"
}

Defining an External Token Provider

Dremio requires the following values to configure an external token provider.

tip

The examples below are specific to configuring Dremio when the external token provider is Microsoft Entra ID. Your identity provider will require additional configuration of a client application registration that depends on the OAuth authorization flow used between your client and your provider. To configure your application registration, consult your identity provider documentation.

Audience

The audience value identifies the intended recipients of the external JWT. It can generally be an array of case-sensitive strings or URI values. The audience is contained in the aud claim in the external JWT.

When using Microsoft Entra ID, the audience can be the Application ID assigned to your app in the Microsoft Entra ID portal or the resource URI. In v2.0 tokens, this value is always the Application ID. In v1.0 tokens, it can be the Application ID or the resource URI used in the request, depending on how the client requested the token. Dremio supports v1.0 and v2.0 JWTs from Microsoft Entra ID.

Example Audience Claim with Microsoft Entra ID Application ID

"aud": "0853fce0-c748-4c54-aa58-f5b9af279840"

User Claim Mapping

The user claim mapping identifies the claim in the external JWT that contains the Dremio username.

When using Microsoft Entra ID authentication, Dremio usernames must align with the User Principal Name (UPN) claim for correct linking of user group memberships via the Azure Graph Client.

When a user is added to a Power BI workspace, the user's identity is also represented by the User Principal Name (UPN), which has the format of an email address.

The JWT contains the UPN claim, named upn, and its value

Example: UPN Claim from Microsoft Entra ID

"upn": "gnarly@dremio.com"

The user claim mapping field of the external token provider requires the name of the claim used in the JWT, which in this case is upn.

Issuer URL

The issuer URL identifies the identity provider that issued the JWT. It is contained in the external JWT's iss claim. When using Microsoft Entra ID, the issuer claim includes the Microsoft Entra ID tenant identifier. Only one external token provider in the system should use the combination of a given audience and issuer.

Example Issuer Claim with Microsoft Entra ID

"iss": "https://login.microsoftonline.com/3e334762-b0c6-4c36-9faf-93800f0d6c71/v2.0"

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. This value is optional; if you do not provide a JWKS URL value when configuring the external token provider, Dremio retrieves the JWKS URL from {issuer URL}/.well-known/openid-configuration.

For Microsoft Entra ID, the JWKS URL is typically of the form https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys.

Example: JWKS URL from Microsoft Entra ID

https://login.microsoftonline.com/58a43618-7933-4e0d-906e-1c1a2a867ad6/discovery/v2.0/keys

Managing External Token Providers

The Dremio administrator or a user with the CONFIGURE SECURITY privilege can view and manage external token providers in Dremio.

Viewing External Token Providers

To view external token providers:

1. In the Dremio console, click on 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

To add an external token provider:

1. In the Dremio console, click in the side navigation bar.
2. In the Settings sidebar, click External Token Providers.
3. Click Add Provider at the top-right corner of the External Token Providers page.
4. In the Add Provider dialog, complete the configuration using the fields described in Defining an External Token Provider above.
5. Click Add.

When you add an external token provider, Dremio automatically enables it. To deactivate it, toggle the Enabled switch on the External Token Providers page.

Each external token provider must use a different combination of issuer and audience. If multiple external token providers share the same issuer and audience, authentication will fail regardless of whether the token providers are enabled.

Editing an External Token Provider

To edit an external token provider:

1. In the Dremio console, click 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 at the right side of the row.
4. In the Edit Provider dialog, click Edit. Update the values using the fields described in Defining an External Token Provider above.

Deleting an External Token Provider

To delete an external token provider:

1. In the Dremio console, click 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 at the right side of the row.
4. In the Delete External Provider dialog, click Delete.

Using the External Token Provider

Retrieving an External JWT

This sample application uses the Microsoft Authentication Library to authenticate a user with the OAuth authorization code flow.

• client_id is the Application (Client) ID assigned to your app by Microsoft Entra ID when the app was registered.
• app_redirect_url or reply URL is the location of the client app where Microsoft Entra ID sends an external JWT after the user has successfully logged in, such as https://myapp.com/auth/callback or http://localhost:3000/auth/callback. The redirect URI is defined in the Microsoft Entra ID application registration for the client.
• dremio_scope_name is the API scope you defined for the client in the Microsoft Entra ID application profile. Dremio requires a scope of dremio.all in token exchange, regardless of the scope configured in the application registration.
• tenant_id is your Microsoft Entra ID tenant identifier.

Example: Retrieving a Microsoft JWT

import msal

client_id = "TODO"
app_redirect_url = "TODO"
dremio_scope_name = "TODO"  
tenant_id = "TODO"

authority_url = "https://login.microsoftonline.com/" + tenant_id
app = msal.PublicClientApplication(client_id, authority = authority_url)
auth_code_flow = app.initiate_auth_code_flow(
    scopes=[dremio_scope_name],
    redirect_uri=app_redirect_url
) # PKCE is included in the msal python library

state = auth_code_flow['state']

authorization_code = "TODO: retrieved from the browser"

external_access_token = ""

if authorization_code:
    auth_result = app.acquire_token_by_auth_code_flow(
        auth_code_flow=auth_code_flow,
        auth_response={"code": authorization_code, "state": state}
    )
    if "access_token" in auth_result:
        external_access_token = auth_result["access_token"]
    else:
        print("Error: no access token")
    if "refresh_token" in auth_result:
        refresh_token = auth_result["refresh_token"]
    else:
        print("Error: no refresh token")
else:
    print("Error: no auth code")

External JWT Exchange

The client must use the Dremio /oauth/token REST API to exchange the JWT for an OAuth access token.