Skip to main content

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

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

If the provider is enabled, then true, otherwise false.

Example: true

Listing All External Token Providers​

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

Method and URL 
GET /v0/external-token-providers/
Example Request: List all external token providers 
curl -X GET 'https://api.dremio.cloud/v0/external-token-providers' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example 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

Creating an External Token Provider​

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

If the provider is available, then true, otherwise false. The default is false.

Example: true

Example Request: Create an external token provider 
curl -X POST 'https://api.dremio.cloud/v0/external-token-providers' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header '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"
}'
Example Response 
No response

Response Status Codes​

204   No Content

400   Bad Request

403   Forbidden

Retrieving an External Token Provider by ID​

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

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

Parameters​

id Path   String (UUID)

Unique identifier of the external token provider.

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

Example Request: Retrieve a specific external token provider 
curl -X GET 'https://api.dremio.cloud/v0/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",
  "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

Updating an External Token Provider​

Update the specified external token provider.

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

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

If the provider is available, then true, otherwise false. The default is false.

Example: true

Example Request: Update an external token provider 
curl -X PUT 'https://api.dremio.cloud/v0/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",
  "issuerUrl": "https://login.microsoftonline.com/959d4644-91e6-4652-9d16-bddeb046c807/v2.0"
  "enabled": true
}'
Example 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

Enabling or Disabling 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)

Unique identifier of the external token provider.

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

Example Request: Enable a specific external token provider 
curl -X PUT 'https://api.dremio.cloud/v0/external-token-providers/a32191f2-ede6-4533-9a17-1532eea015aa/enable' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
}'
Example Response 
No response

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 /v0/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: Delete an external token provider 
curl -X DELETE 'https://api.dremio.cloud/v0/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