Skip to main content
Version: 24.3.x

External Token Providers Enterprise

Use the External Token Providers API to manage external token providers that enable client applications to use a JSON Web Token (JWT) issued by an identity provider to authenticate to Dremio.

External Token Providers Object 
{
  "id": "a32191f2-ede6-4533-9a17-1532eea015aa",
  "name": "My Token Provider",
  "audience": [
    "f7fdd9e0-8332-4131-95ce-b350c3bbeab2"
  ],
  "userClaim": "upn",
  "issuer": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0",
  "jwks": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "type": "JWT",
  "state": "ENABLED"
}

External Token Providers Attributes​

id String (UUID)

Unique identifier of the external token provider. Generated by Dremio and immutable.

Example: a32191f2-ede6-4533-9a17-1532eea015aa

name String

User-provided name of the external token provider. Used for display only.

Example: My Token Provider

audience Array of String

Intended recipients of the JSON Web Token (JWT). If there is only one audience for the JWT, then the audience value contains only one string.

Example: ["f7fdd9e0-8332-4131-95ce-b350c3bbeab2"]

userClaim String

Key name for the target claim in the JSON Web Token (JWT). The target claim's value corresponds to the Dremio username.

Example: upn

issuer String

URL that identifies the principal that issued the JSON Web Token (JWT).

Example: https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0

jwks String

Endpoint that hosts the JWK Set (JWKS), a set of public keys used to verify the JSON Web Token (JWT) signature.

Example: https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys

type String

Type of the tokens associated with the external token provider. The type is always JWT.

state String

Current state of the external token provider: ENABLED (default) or DISABLED.

Example: ENABLED

Listing All External Token Providers​

Retrieve a list of all available external token providers and the metadata for each provider.

Method and URL 
GET /api/v3/external-token-providers/

Parameters​

pageToken Query   Query   Optional

Token for retrieving the next page of external token providers. If the Dremio instance has more providers than the maximum per page (default 5), the response will include a nextPageToken after the data array. Use the nextPageToken value in your request URL as the pageToken value. Do not change any other query parameters included in the request URL when you use pageToken. Read pageToken Query Parameter for usage examples.

limit Query   Integer   Optional

Number of rows to return. Maximum valid value is 99. Default is 5. Read Limit and Offset Query Parameters for usage examples.

Example Request 
curl -X GET 'https://{hostname}/api/v3/external-token-providers' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example Response 
{
  "data": [
    {
      "id": "d21bbf72-6ab7-45e8-9466-ae1d9ffe92a7",
      "name": "My First Provider",
      "type": "JWT",
      "state": "DISABLED"
    },
    {
      "id": "a32191f2-ede6-4533-9a17-1532eea015aa",
      "name": "My Token Provider",
      "type": "JWT",
      "state": "ENABLED"
    }
  ]
}

Response Status Codes​

200   OK

403   Forbidden

Creating an External Token Provider​

Create an external token provider.

Method and URL 
POST /api/v3/external-token-providers

Parameters​

name Body   String

Name to use for the external token provider.

Example: My Token Provider

audience Body   Array of String

Intended recipients of the JSON Web Token (JWT).

Example: ["f7fdd9e0-8332-4131-95ce-b350c3bbeab2"]

userClaim Body   String

Key name for the target claim in the JSON Web Token (JWT). The target claim's value corresponds to the Dremio username.

Example: upn

issuer Body   String

URL that identifies the principal that issued the JSON Web Token (JWT).

Example: https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0

jwks Body   String   Optional

Endpoint that hosts the JWK Set (JWKS), a set of public keys used to verify the JSON Web Token (JWT) signature. If you do not provide a jwks value, Dremio retrieves the value from <issuer>/.well-known/openid-configuration.

Example: https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys

Example Request 
curl -X POST 'https://{hostname}/api/v3/external-token-providers' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "My Token Provider",
  "audience": [
    "f7fdd9e0-8332-4131-95ce-b350c3bbeab2"
  ],
  "issuer": "https://login.microsoftonline.com/3e334762-b0c6-4c36-9faf-93800f0d6c71/v2.0",
  "jwks": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "userClaim": "upn"
}'
Example Response 
{
  "id": "a32191f2-ede6-4533-9a17-1532eea015aa",
  "name": "My Token Provider",
  "audience": [
    "f7fdd9e0-8332-4131-95ce-b350c3bbeab2"
  ],
  "userClaim": "upn",
  "issuer": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0",
  "jwks": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "type": "JWT",
  "state": "ENABLED"
}

Response Status Codes​

200   OK

400   Bad Request

403   Forbidden

Retrieving an External Token Provider by ID​

Retrieve a specific external token provider by the providers's ID.

Method and URL 
GET /api/v3/external-token-providers/{id}

Parameters​

id Path   String (UUID)

Unique identifier of the external token provider.

Example:a32191f2-ede6-4533-9a17-1532eea015aa

Example Request 
curl -X GET 'https://{hostname}/api/v3/external-token-providers/a32191f2-ede6-4533-9a17-1532eea015aa' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example Response 
{
  "id": "a32191f2-ede6-4533-9a17-1532eea015aa",
  "name": "My Token Provider",
  "audience": [
    "f7fdd9e0-8332-4131-95ce-b350c3bbeab2"
  ],
  "userClaim": "upn",
  "issuer": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0",
  "jwks": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "type": "JWT",
  "state": "ENABLED"
}

Response Status Codes​

200   OK

403   Forbidden

404   Not Found

Updating an External Token Provider​

Update the specified external token provider.

Method and URL 
PUT /api/v3/external-token-providers/{id}

Parameters​

id Path   String (UUID)

Unique identifier of the external token provider.

Example: a32191f2-ede6-4533-9a17-1532eea015aa

name Body   String

User-provided name of the external token provider.

Example: My Token Provider

audience Body   Array of String

Intended recipients of the JSON Web Token (JWT). If there is only one audience for the JWT, then the audience value contains only one string.

Example: ["28edee01-4d0d-46ed-b1ae-52139bc3b3ad"]

userClaim Body   String

Key name for the target claim in the JSON Web Token (JWT). The target claim's value corresponds to the Dremio username.

Example: preferred_username

issuer Body   String

URL that identifies the principal that issued the JSON Web Token (JWT).

Example: https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0

jwks Body   String   Optional

Endpoint that hosts the JWK Set (JWKS), a set of public keys used to verify the JSON Web Token (JWT) signature. If you do not provide a jwks value, Dremio retrieves the value from <issuer>/.well-known/openid-configuration using the updated issuer.

Example: https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys

type Body   String   Optional

Type of the tokens associated with the external token provider. The type is always JWT.

Example: JWT

state Body   String   Optional

Current state of the external token provider: ENABLED or DISABLED. If the update request does not include the state parameter, Dremio does not change the state.

Example: ENABLED

Example Request 
curl -X PUT 'https://{hostname}/api/v3/external-token-providers/a32191f2-ede6-4533-9a17-1532eea015aa' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "My Token Provider",
  "audience": [
    "28edee01-4d0d-46ed-b1ae-52139bc3b3ad"
  ],
  "userClaim": "preferred_username",
  "issuer": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0"
}'
Example Response 
{
  "id": "a32191f2-ede6-4533-9a17-1532eea015aa",
  "name": "My Token Provider",
  "audience": [
    "28edee01-4d0d-46ed-b1ae-52139bc3b3ad"
  ],
  "userClaim": "preferred_username",
  "issuer": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0",
  "jwks": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "type": "JWT",
  "state": "ENABLED"
}

Response Status Codes​

200   OK

400   Bad Request

403   Forbidden

404   Not Found

Updating an External Token Provider's State​

Update the state for the specified external token provider.

Method and URL 
PATCH /api/v3/external-token-providers/{id}/state

Parameters​

id Path   String (UUID)

Unique identifier of the external token provider.

Example: a32191f2-ede6-4533-9a17-1532eea015aa

state Body   String

Current state of the external token provider: ENABLED or DISABLED.

Example: DISABLED

Example Request 
curl -X PUT 'https://{hostname}/api/v3/external-token-providers/a32191f2-ede6-4533-9a17-1532eea015aa/state' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "state": "DISABLED"
}'

A successful request to update the state for an external token provider returns an empty response with the HTTP 204 No Content status response code.

Response Status Codes​

204   No Content

400   Bad Request

403   Forbidden

404   Not Found

Deleting an External Token Provider​

Delete the specified external token provider.

Method and URL 
DELETE /api/v3/external-token-providers/{id}

Parameters​

id Path   String (UUID)

Unique identifier of the external token provider that you want to delete.

Example: a32191f2-ede6-4533-9a17-1532eea015aa

Example Request 
curl -X DELETE 'https://{hostname}/api/v3/external-token-providers/a32191f2-ede6-4533-9a17-1532eea015aa' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example Response 
No response

Response Status Codes​

204   No Content

403   Forbidden