On this page

    External Token Providers

    This topic describes the Dremio concept of external token providers, which allow for the exchanging JSON Web Tokens (JWT) between Dremio Cloud and an OpenID Connect (OIDC) identity provider (IdP). These token can then be used for single sign-on (SSO) between the client application and Dremio Cloud.

    Overview

    External token providers facilitate the authorization of client applications in using Dremio Cloud by exchanging JWTs, which are lightweight and easy to use. SSO providers also widely accept JWTs.

    Dremio serves as a resource provider and authorization server in the event of SSO, when AAD is used as an authentication server for a client application. However, these providers also serve as an external authorization server when configured in Dremio using external token providers.

    The following figure illustrates how an external token provider authorizes a user on a client application.

    The authorization process for these tokens is as described below:

    1. An admin enables Azure AD as a token provider using Dremio’s Power BI Authentication feature.
    2. A user connects to the client application, whereupon the user is sent to the external token provider.
    3. The token provider authenticates the user, obtains their consent, and returns an authorization code followed by a JWT to the client application.
    4. The client application exchanges the JWT for a Dremio token.
    5. The client application then uses the Dremio token to connect to the Dremio service.
    6. Dremio verifies the user using the token and grants access only to resources the user has permissions for.

    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.
    • Users can typically pick their preferred OIDC IdP to generate a token.
    • 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 easily be leaked or misused.

    When to Use JWTs

    The use cases for JWTs extend to a limited range of instances, which makes it incredibly important to understand the best practices of external tokens. External tokens serve as a portable unit of identity, which may be passed between services and applications as needed to verify a user’s identity. However, these tokens should not be used for sessions, but instead for the following use cases:

    • API authentication
    • Server-to-server authorization

    Understanding JWT Claim Values

    The following sections offer additional context regarding the values required to correctly enable the external token provider functionality. Each of these sections will reference the following example declaration from the JWT Claims Set of a JWT, as provided by Internet Assigned Numbers Authority (IANA):

    {
    "iss": "https://server.example.com",
    "preferred_username": "user@dremio.com",
    "aud": "https://client.example.org",
    "exp": 1440804813,
    "cnf":{
      "jku": "https://keys.example.net/pop-keys.json",
      "kid": "2015-08-28"
     }
    }
    

    Audience

    The Audience field identifies the recipient(s) the JWT is intended for, which is typically application-specific. In order to process the JWT, an audience claim must be included. If the audience is absent, the claim will be rejected outright. The audience claim is identified by the aud member, which contains an array of case-sensitive strings, consisting of a StringOrURI value. In the event of only a single audience, then one string will be found here, as shown in the example below:

    "aud": "https://client.example.org",
    

    User Claim Mapping

    The User Claim Mapping field identifies the specific user the JWT is being used for, which should consist of their Dremio Cloud email address. This is considered a private claim name, but is required from an IdP to identify a user’s permissions and access. The field in Dremio is used to identify whatever custom claim is attached to usernames depending on the provider, such as preferred_username.

    note:

    In order to use a JWT for user claims, the included username must already exist on Dremio Cloud.

    From the example above, a user would appear as:

    "preferred_username": "user@dremio.com",
    

    Issuer URL

    The Issuer URL identifies the original entity that issued the JWT, which is typically application-specific. The issuer may be identified by the iss member, a case-sensitive string containing a single StringOrURI value. This is required for Dremio.

    From the example above, an issuer would appear as:

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

    JWKS URL

    The JWKS URL field is specifically used when a proof-of-possession key is provided as a reference rather than a value. This is done using the jku member, which is a URI referring to a resource for JSON-encoded public keys. These keys are represented as a JWK Set (JWKS), which includes the key.

    From the example above, consider the following claim:

    "cnf":{
      "jku": "https://keys.example.net/pop-keys.json",
      "kid": "2015-08-28"
     }
    

    The jku value is used for the JWKS URL field in Dremio. However, if multiple keys are used, a “kid” must also be identified in the JRT and found within the referenced JWKS. That key should also contain the same “kid” value.

    Viewing External Token Providers

    Perform the following steps to view external token providers:

    1. From Dremio Cloud, click the Settings (gear) icon on the left sidebar.

    2. Select Organization Settings from the menu.

    3. On the Organization Settings page, click External Token Providers from the left sidebar.

    Adding an External Token Provider

    Perform the following steps to add an external token provider:

    note:

    See Understanding JWT Claim Values 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, for Name, enter a name for the client application.

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

    note:

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

    1. For User Claim Mapping, enter the private claim that maps to the Dremio username.
    2. 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.

    1. (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.
    2. Click Save.

    Editing an External Token Provider

    Perform the following steps to edit an external token provider:

    note:

    All parameters are optional in an edit operation.

    note:

    See Understanding JWT Claim Values for additional 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.

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

    2. 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.

    1. (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.
    2. 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.