Skip to main content

External Token Providers

You can use a JSON Web Token (JWT) issued by your OAuth Server to establish ODBC/JDBC connections to Dremio Cloud. The OAuth Server can be any provider (including an Identity Provider) that can generate a JWT.

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

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

The following figure illustrates an example of 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, and the client application 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 accesses the report/dashboard in the client application that uses a Dremio data source. If the user allows the client application to access Dremio, the IdP issues a JWT to the client application for that user.

  4. The client application sends a ODBC/JDBC connection request using the Dremio driver and using the JWT as the password (along with an empty username), and sets the property token_type to jwt. See Construct a Connection String for JDBC Applications for more information.

  5. Dremio's SQL interface sends the JWT to Dremio’s Authentication Service for validation. Dremio’s Authentication Service validates the authenticity of the JWT. The authentication service then returns the user information (extracted from the JWT) to the SQL interface.

  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, and the connection is closed when the token 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 are provided by an OIDC IdP. 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 these tokens. Typically, such tokens are centrally managed and inaccessible by users.
  • Tokens may be generated with short expiration periods of minutes or hours, making these tokens even more secure as they cannot be easily leaked or misused.
  • 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 regarding the values required to correctly enable the external token provider functionality. Each of these sections reference the following 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 recipients that the JWT is intended for, which can be application-specific or provider-specific. For the JWT to be processed, the aud claim must be included. If the aud claim is absent, the JWT will be rejected outright. The aud claim value is an array of case-sensitive strings, consisting of a StringOrURI value. 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:

Example with multiple audiences
"aud": "https://client.example.org,https://client.example2.org"
note

The combination of a given audience and a given issuer can only be used by one external token provider in the organization. If you have multiple organizations, this rule remains across multiple organizations.

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 specific user the JWT is being used for, which should consist of their Dremio username. This is considered a private claim name, but is required from an IdP to identify a user's permissions and access. The JWT must include the user claim mapping.

As an example, in Power BI with Azure Active Directory, the user claim is upn, which is a basic claim in v1.0 access tokens. If you are using a different Token Provider with a user claim other than upn, specify that user claim in the User Claim Mapping field.

Issuer URL​

The Issuer URL field identifies the principal that issued the JWT, which is typically provider-specific(authorization-server-specific). The value provided for the issuer URL field must match the iss claim value, which is a case-sensitive string containing a single StringOrURI value. The JWT Claim Set must include the iss 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",
note

A given issuer URL and audience can only be used by one external token provider and one organization.

JWKS URL​

The JWKS URL field 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 the "jwks_uri" field from <issuer>/.well-known/openid-configuration.

Viewing External Token Providers​

Perform the following steps to view external token providers:

  1. From Dremio Cloud, click the Organization (building) icon in the side navigation bar.
  2. Click the Settings (gear) icon at the top of the page.
  3. On the Organization Settings page, click External Token Providers on the left sidebar.
This is a screenshot showing the External Token Providers page.

Adding an External Token Provider​

Perform the following steps to add an external token provider:

note

See Understanding the Required Fields for External Token Providers for claim information.

  1. From the Organization Settings page, click External Token Providers on the left sidebar.

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

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

    This is a screenshot showing how to add an External Token Provider.

    a. For Name, enter a name for the client application.

    b. For Audience, enter the value that identifies the intended recipients of the JWT being added.

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

    d. For Issuer URL, enter the URL (using the https scheme with no query or fragment component) of the IdP you want to connect to. Dremio will normalize the issuer URL.

    e. (Optional) For JWKS URL, enter the URL of the IdP's JSON Web Key Set document. If not provided, Dremio will retrieve it from {issuerUrl}/.well-known/openid-configuration.

  4. Click Save.

Editing an External Token Provider​

All parameters are optional in an edit operation. Perform the following steps to edit an external token provider:

note

See Understanding the Required Fields for External Token Providers for claim information.

  1. From the Organization Settings page, click External Providers on the left sidebar.

  2. From the External Token Providers page, click the Edit icon for the external token provider that you want to edit.

  3. From the Edit Provider dialog, enter a name for the client application for Name.

  4. For Audience, enter the value that identifies the intended recipients of this JWT that is being added.

    note

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

  5. For User Claim Mapping, enter the claim of the external JWT that maps to the Dremio username.

  6. For Issuer URL, enter the URL (using the https scheme with no query or fragment component) of the IdP you want to connect to. Dremio will normalize the issuer URL.

    note

    A given issuer URL and audience can only be used by one external token provider and one organization.

  7. (Optional) For JWKS URL, enter the URL of the IdP's JSON Web Key Set document. If not provided, Dremio will retrieve it from {issuerUrl}/.well-known/openid-configuration.

  8. Click Save.

Deleting an External Token Provider​

Perform the steps below to delete an external token provider:

  1. From the Organization Settings page, click External Providers on the left-hand sidebar menu.
  2. From the External Token Providers page, click the Delete icon for the external token provider that you wish to delete.
  3. Confirm that you wish to delete the external token provider.