Skip to main content

External Token Providers

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",
  "issuerUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0",
  "jwksUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "enabled": true
}

External Token Provider Attributes​

id String (UUID)

UUID of the external token provider. Generated by Dremio and immutable.

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, 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

issuerUrl 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

jwksUrl 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

enabled Boolean

Whether the provider is enabled. Returns true if enabled, false otherwise.

List All External Token Providers​

Method and URL 
GET /v0/external-token-providers/

Example​

Request 
curl -X GET 'https://api.dremio.cloud/v0/external-token-providers' \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'
Response 
[
  {
     "id": "d21bbf72-6ab7-45e8-9466-ae1d9ffe92a7",
     "name": "My First Provider",
     "enabled": true
  },
  {
     "id": "a32191f2-ede6-4533-9a17-1532eea015aa",
     "name": "My Token Provider",
     "enabled": true
  }
]

Response Status Codes​

200   OK

403   Forbidden

Create an External Token Provider​

Method and URL 
POST /v0/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

issuerUrl 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

jwksUrl 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 jwksUrl value, Dremio retrieves the value from <issuerUrl>/.well-known/openid-configuration.

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

enabled Body   Boolean   Optional

Whether the provider is enabled. Set to true to enable, false to disable. The default is false.

Example​

Request 
curl -X POST 'https://api.dremio.cloud/v0/external-token-providers' \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
--data-raw '{
  "name": "My Token Provider",
  "audience": [
    "f7fdd9e0-8332-4131-95ce-b350c3bbeab2"
  ],
  "issuerUrl": "https://login.microsoftonline.com/3e334762-b0c6-4c36-9faf-93800f0d6c71/v2.0",
  "jwksUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "userClaim": "upn"
}'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes​

204   No Content

400   Bad Request

403   Forbidden

Retrieve an External Token Provider by ID​

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

Parameters​

id Path   String (UUID)

UUID of the external token provider.

Example​

Request 
curl -X GET "https://api.dremio.cloud/v0/external-token-providers/$EXTERNAL_TOKEN_PROVIDER_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'
Response 
{
  "id": "a32191f2-ede6-4533-9a17-1532eea015aa",
  "name": "My Token Provider",
  "audience": [
    "f7fdd9e0-8332-4131-95ce-b350c3bbeab2"
  ],
  "userClaim": "upn",
  "issuerUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0",
  "jwksUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "enabled": true
}

Response Status Codes​

200   OK

403   Forbidden

404   Not Found

Update an External Token Provider​

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

Parameters​

id Path   String (UUID)

UUID of the external token provider.

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

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

issuerUrl 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

jwksUrl 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 jwksUrl value, Dremio retrieves the value from <issuerUrl>/.well-known/openid-configuration using the updated issuer.

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

enabled Body   Boolean   Optional

Whether the provider is enabled. Set to true to enable, false to disable. The default is false.

Example​

Request 
curl -X PUT "https://api.dremio.cloud/v0/external-token-providers/$EXTERNAL_TOKEN_PROVIDER_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
--data-raw '{
  "name": "My Token Provider",
  "audience": [
    "28edee01-4d0d-46ed-b1ae-52139bc3b3ad"
  ],
  "userClaim": "preferred_username",
  "issuerUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0",
  "enabled": true
}'
Response 
{
  "id": "a32191f2-ede6-4533-9a17-1532eea015aa",
  "name": "My Token Provider",
  "audience": [
    "28edee01-4d0d-46ed-b1ae-52139bc3b3ad"
  ],
  "userClaim": "preferred_username",
  "issuerUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0",
  "jwksUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/discovery/v2.0/keys",
  "enabled": true
}

Response Status Codes​

200   OK

400   Bad Request

403   Forbidden

404   Not Found

Enable or Disable an External Token Provider​

Enable the specified external token provider.

Method and URL 
PUT /v0/external-token-providers/{id}/enable

Disable the specified external token provider.

Method and URL 
PUT /v0/external-token-providers/{id}/disable

Parameters​

id Path   String (UUID)

UUID of the external token provider.

Example​

Request 
curl -X PUT "https://api.dremio.cloud/v0/external-token-providers/$EXTERNAL_TOKEN_PROVIDER_ID/enable" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes​

204   No Content

400   Bad Request

403   Forbidden

404   Not Found

Delete an External Token Provider​

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

Parameters​

id Path   String (UUID)

UUID of the external token provider that you want to delete.

Example​

Request 
curl -X DELETE "https://api.dremio.cloud/v0/external-token-providers/$EXTERNAL_TOKEN_PROVIDER_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes​

204   No Content

403   Forbidden