Skip to main content
Version: current [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