OpenID Connect Methods

Using the OpenID Connect (OIDC) methods of the Tableau REST API you can:

  • Set your Tableau Cloud site to use OIDC authentication to authenticate users 
    • Configure OIDC authentication when your identity provider (IdP) does not provide a configuration URL (in other words, a URL that ends with .well-known/openid-configuration)
    • Configure client authentication, custom scope, prompt, essential ACR Values, or voluntary ACR values that the Tableau Cloud's OIDC configuration UI does not support
  • Get details about the OIDC configuration
  • Update your OIDC configuration
  • Remove your OIDC configuration

The above functionality relates to OIDC elements described at: OpenID Connect(Link opens in a new window).

Create OpenID Connect Configuration

Create the Tableau Cloud site's OpenID Connect (OIDC) configuration.

After you've configured OIDC authentication, you can use the Tableau Cloud's UI to test the configuration(Link opens in a new window) and add users(Link opens in a new window).

For more information about OIDC authentication in Tableau Cloud, see OpenID Connect(Link opens in a new window) in the Tableau Cloud Help.

Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server.Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Cloud site admins only.

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/site-oidc-configuration

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.

Request Body

Copy
<tsRequest>
  <siteOIDCConfiguration
    enabled="enabled"
    clientId="clientId"
    clientSecret="clientSecret"
    authorizationEndpoint="authorizationEndpoint"
    tokenEndpoint="tokenEndpoint"
    userinfoEndpoint="userinfoEndpoint"
    jwksUri="jwksUri"
    endSessionEndpoint="endSessionEndpoint"
    allowEmbeddedAuthentication="allowEmbeddedAuthentication"
    prompt="prompt"
    customScope="customScope"
    clientAuthentication="clientAuthentication"
    essentialAcrValues="essentialAcrValues"
    voluntaryAcrValues="voluntaryAcrValues"
    emailMapping="emailMapping"
    firstNameMapping="firstNameMapping"
    lastNameMapping="lastNameMapping"
    fullNameMapping="fullNameMapping"
    useFullName="useFullName" />
</tsRequest>

Copy
{
  "siteOIDCConfiguration": {
    "enabled": "enabled",
    "clientId": "clientId",
    "clientSecret": "clientSecret",
    "authorizationEndpoint": "authorizationEndpoint",
    "tokenEndpoint": "tokenEndpoint",
    "userinfoEndpoint": "userinfoEndpoint",
    "jwksUri": "jwksUri",
    "endSessionEndpoint": "endSessionEndpoint",
    "allowEmbeddedAuthentication": "allowEmbeddedAuthentication",
    "prompt":"prompt",
    "customScope":"customScope",
    "clientAuthentication": "clientAuthentication",
    "essentialAcrValues": "essentialAcrValues",
    "voluntaryAcrValues": "voluntaryAcrValues",
    "emailMapping": "emailMapping",
    "firstNameMapping": "firstNameMapping",
    "lastNameMapping": "lastNameMapping",
    "fullNameMapping": "fullNameMapping",
    "useFullName": "useFullName"
    }
}

Request Attributes

enabled (Required) Controls whether the configuration is enabled or not. Value can be "true" or "false". For example "true".
clientId (Required) The client ID from your IdP. For example, "0oa111usf1gpUkVUt0h1".
clientSecret (Required) The client secret from your IdP.
authorizationEndpoint (Required) Use the authorization endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (authorization_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/authorize".
tokenEndpoint (Required) Use the token endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the token endpoint (token_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/token".
userinfoEndpoint (Required) Use the user information endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (userinfo_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/userinfo".
jwkUri (Required) Use the JWK set URI from your IdP. To find the value, enter the configuration URL in a browser and obtain the JWK set URI endpoint (jwks_uri) from the details that are returned. For example, "https://myidp.com/oauth2/v1/keys".
endSessionEndpoint (Optional) If single logout (SLO) is enabled for the site, which is done through Tableau Cloud site UI, you can specify the configuration URL or the end session endpoint from your IdP. For example, "https://myidp.com/oauth2/v1/logout".
allowEmbeddedAuthentication (Optional) Controls how users authenticate when accessing embedded views. Value can be "true" or "false". Default value is "false", which authenticates users in a separate pop-up window. When set to "true", users authenticate using an inline frame (IFrame), which is less secure.
customScope (Optional) Specifies a custom scope user-related value that you can use to query the IdP. For example, "openid, email, profile".
prompt (Optional) Specifies whether the user is prompted for re-authentication and consent. For example, "login, consent".
clientAuthentication (Optional) Token endpoint authentication method. Value can be "client_secret_basic" or "client_secret_post". Default value is "client_secret_basic".
essentialAcrValues (Optional) List of essential Authentication Context Reference Class values used for authentication. For example, "phr".
voluntaryAcrValues (Optional) List of voluntary Authentication Context Reference Class values used for authentication.
emailMapping (Optional) Claim for retrieving email from the OIDC token. Default value is "email".
firstNameMapping (Optional) Claim for retrieving first name from the OIDC token. Default value is "given_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false".
lastNameMapping (Optional) Claim for retrieving last name from the OIDC token. Default value is "family_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false".
fullNameMapping (Optional) Claim for retrieving name from the OIDC token. Default value is "name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "true".
useFullName (Optional) Controls what is used as the display name. Value can be "true" or "false". Default value is "false", which uses first name (firstNameMapping attribute) and last name (lastNameMapping attribute) as the user display name. When set to "true", full name (fullNameMapping attribute) is used as the user display name.

cURL Request Example

curl "https://us-west-2a.online.tableau.com/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-update-oidc-config.xml

Content of create-update-oidc-config.xml:

Copy
<tsRequest>
  <siteOIDCConfiguration
    enabled="enabled"
    clientId="clientId"
    clientSecret="clientSecret"
    authorizationEndpoint="authorizationEndpoint"
    tokenEndpoint="tokenEndpoint"
    userinfoEndpoint="userinfoEndpoint"
    jwksUri="jwksUri"
    endSessionEndpoint="endSessionEndpoint"
    allowEmbeddedAuthentication="allowEmbeddedAuthentication"
    prompt="prompt"
    customScope="customScope"
    clientAuthentication="clientAuthentication"
    essentialAcrValues="essentialAcrValues"
    voluntaryAcrValues="voluntaryAcrValues"
    emailMapping="emailMapping"
    firstNameMapping="firstNameMapping"
    lastNameMapping="lastNameMapping"
    fullNameMapping="fullNameMapping"
    useFullName="useFullName" />
</tsRequest

Response Code

200

Response Body

Copy
<tsResponse>
  <siteOIDCConfiguration
    enabled="true" 
    testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
    allowEmbeddedAuthentication="false"
    clientId="0oa111usf1gpUkVUt0h1" 
    clientSecret="&lt;omit>"
    authorizationEndpoint="https://myidp.com/oauth2/v1/authorize"
    tokenEndpoint="https://myidp.com/oauth2/v1/token"
    userinfoEndpoint="https://myidp.com/oauth2/v1/userinfo"
    jwksUri="https://myidp.com/oauth2/v1/keys"
    endSessionEndpoint="https://myidp.com/oauth2/v1/logout"
    customScope="openid, email, profile"
    prompt="login,consent"
    clientAuthentication="client_secret_basic"
    essentialAcrValues="phr"
    emailMapping="email"
    firstNameMapping="given_name"
    lastNameMapping="family_name"
    fullNameMapping="name"
    useFullName="false" />
</tsResponse>
Copy
{tsRequest:
}

Notes:

  • The response hides the client secret and replaces it with &lt;omit>.

  • You can use the testloginURL to validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.

Errors

HTTP status error Code Condition Details
400 400000 Bad Request The content of the request body is missing or incomplete, or contains malformed XML.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.

For more information, see Handling Errors.

Get OpenID Connect Configuration

Get details about the Tableau Cloud site's OpenID Connect (OIDC) configuration.

Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Cloud site admins only.

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

GET /api/api-version/sites/site-luid/site-oidc-configuration

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.

Request Body

None

cURL Request Example

curl "https://us-west-2a.online.tableau.com/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy
<tsResponse>
  <siteOIDCConfiguration
    enabled="true" 
    testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
    allowEmbeddedAuthentication="false"
    clientId="0oa111usf1gpUkVUt0h1" 
    clientSecret="&lt;omit>"
    authorizationEndpoint="https://myidp.com/oauth2/v1/authorize"
    tokenEndpoint="https://myidp.com/oauth2/v1/token"
    userinfoEndpoint="https://myidp.com/oauth2/v1/userinfo"
    jwksUri="https://myidp.com/oauth2/v1/keys"
    endSessionEndpoint="https://myidp.com/oauth2/v1/logout"
    customScope="openid, email, profile"
    prompt="login,consent"
    clientAuthentication="client_secret_basic"
    essentialAcrValues="phr"
    emailMapping="email"
    firstNameMapping="given_name"
    lastNameMapping="family_name"
    fullNameMapping="name"
    useFullName="false" />
</tsResponse>
Copy
{tsResponse:
}

Notes:

  • The response hides the client secret and replaces it with &lt;omit>.

  • You can use the testloginURL to validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.

Errors

HTTP status error Code Condition Details
400 400000 Bad Request The content of the request body is missing or incomplete, or contains malformed XML.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.

For more information, see Handling Errors.

Remove OpenID Connect Configuration

Disable and clear the Tableau Cloud site's OpenID Connect (OIDC) configuration.

Important: Before removing the OIDC configuration, make sure that users who are set to authenticate with OIDC are set to use a different authentication type. Users who are not set with a different authentication type before removing the OIDC configuration will not be able to sign in to Tableau Cloud.

Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Cloud site admins only.

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/disable-oidc-configuration

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.

Request Body

None

cURL Request Example

curl "https://us-west-2a.online.tableau.com/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/disable-oidc-configuration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

None

Errors

HTTP status error Code Condition Details
400 400000 Bad Request The content of the request body is missing or incomplete, or contains malformed XML.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.

For more information, see Handling Errors.

Update OpenID Connect Configuration

Update the Tableau Cloud site's OpenID Connect (OIDC) configuration.

Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server.Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Cloud site admins only.

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/site-oidc-configuration

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.

Request Body

Copy
<tsRequest>
  <siteOIDCConfiguration
    enabled="enabled"
    clientId="clientId"
    clientSecret="clientSecret"
    authorizationEndpoint="authorizationEndpoint"
    tokenEndpoint="tokenEndpoint"
    userinfoEndpoint="userinfoEndpoint"
    jwksUri="jwksUri"
    endSessionEndpoint="endSessionEndpoint"
    allowEmbeddedAuthentication="allowEmbeddedAuthentication"
    prompt="prompt"
    customScope="customScope"
    clientAuthentication="clientAuthentication"
    essentialAcrValues="essentialAcrValues"
    voluntaryAcrValues="voluntaryAcrValues"
    emailMapping="emailMapping"
    firstNameMapping="firstNameMapping"
    lastNameMapping="lastNameMapping"
    fullNameMapping="fullNameMapping"
    useFullName="useFullName" />
</tsRequest>

Copy
{
  "siteOIDCConfiguration": {
    "enabled": "enabled",
    "clientId": "clientId",
    "clientSecret": "clientSecret",
    "authorizationEndpoint": "authorizationEndpoint",
    "tokenEndpoint": "tokenEndpoint",
    "userinfoEndpoint": "userinfoEndpoint",
    "jwksUri": "jwksUri",
    "endSessionEndpoint": "endSessionEndpoint",
    "allowEmbeddedAuthentication": "allowEmbeddedAuthentication",
    "prompt":"prompt",
    "customScope":"customScope",
    "clientAuthentication": "clientAuthentication",
    "essentialAcrValues": "essentialAcrValues",
    "voluntaryAcrValues": "voluntaryAcrValues",
    "emailMapping": "emailMapping",
    "firstNameMapping": "firstNameMapping",
    "lastNameMapping": "lastNameMapping",
    "fullNameMapping": "fullNameMapping",
    "useFullName": "useFullName"
    }
}

Request Attributes

Note: Because partial updates are not supported therefore, you must include all the needed attributes in your request to ensure the configuration update is completed successfully.

enabled (Required) Controls whether the configuration is enabled or not. Value can be "true" or "false". For example "true".
clientId (Required) The client ID from your IdP. For example, "0oa111usf1gpUkVUt0h1".
clientSecret (Required) The client secret from your IdP.
authorizationEndpoint (Required) Use the authorization endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (authorization_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/authorize".
tokenEndpoint (Required) Use the token endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the token endpoint (token_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/token".
userinfoEndpoint (Required) Use the user information endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (userinfo_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/userinfo".
jwkUri (Required) Use the JWK set URI from your IdP. To find the value, enter the configuration URL in a browser and obtain the JWK set URI endpoint (jwks_uri) from the details that are returned. For example, "https://myidp.com/oauth2/v1/keys".
endSessionEndpoint (Optional) If single logout (SLO) is enabled for the site, which is done through Tableau Cloud site UI, you can specify the configuration URL or the end session endpoint from your IdP. For example, "https://myidp.com/oauth2/v1/logout".
allowEmbeddedAuthentication (Optional) Controls how users authenticate when accessing embedded views. Value can be "true" or "false". Default value is "false", which authenticates users in a separate pop-up window. When set to "true", users authenticate using an inline frame (IFrame), which is less secure.
customScope (Optional) Specifies a custom scope user-related value that you can use to query the IdP. For example, "openid, email, profile".
prompt (Optional) Specifies whether the user is prompted for re-authentication and consent. For example, "login, consent".
clientAuthentication (Optional) Token endpoint authentication method. Value can be "client_secret_basic" or "client_secret_post". Default value is "client_secret_basic".
essentialAcrValues (Optional) List of essential Authentication Context Reference Class values used for authentication. For example, "phr".
voluntaryAcrValues (Optional) List of voluntary Authentication Context Reference Class values used for authentication.
emailMapping (Optional) Claim for retrieving email from the OIDC token. Default value is "email".
firstNameMapping (Optional) Claim for retrieving first name from the OIDC token. Default value is "given_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false".
lastNameMapping (Optional) Claim for retrieving last name from the OIDC token. Default value is "family_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false".
fullNameMapping (Optional) Claim for retrieving name from the OIDC token. Default value is "name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "true".
useFullName (Optional) Controls what is used as the display name. Value can be "true" or "false". Default value is "false", which uses first name (firstNameMapping attribute) and last name (lastNameMapping attribute) as the user display name. When set to "true", full name (fullNameMapping attribute) is used as the user display name.

cURL Request Example

curl "https://us-west-2a.online.tableau.com/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuratioin" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-update-oidc-config.xml

Content of create-update-oidc-config.xml:

Copy
<tsRequest>
  <siteOIDCConfiguration
    enabled="enabled"
    clientId="clientId"
    clientSecret="clientSecret"
    authorizationEndpoint="authorizationEndpoint"
    tokenEndpoint="tokenEndpoint"
    userinfoEndpoint="userinfoEndpoint"
    jwksUri="jwksUri"
    endSessionEndpoint="endSessionEndpoint"
    allowEmbeddedAuthentication="allowEmbeddedAuthentication"
    prompt="prompt"
    customScope="customScope"
    clientAuthentication="clientAuthentication"
    essentialAcrValues="essentialAcrValues"
    voluntaryAcrValues="voluntaryAcrValues"
    emailMapping="emailMapping"
    firstNameMapping="firstNameMapping"
    lastNameMapping="lastNameMapping"
    fullNameMapping="fullNameMapping"
    useFullName="useFullName" />
</tsRequest

Response Code

200

Response Body

Copy
<tsResponse>
  <siteOIDCConfiguration
    enabled="true" 
    testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
    allowEmbeddedAuthentication="false"
    clientId="0oa111usf1gpUkVUt0h1" 
    clientSecret="&lt;omit>"
    authorizationEndpoint="https://myidp.com/oauth2/v1/authorize"
    tokenEndpoint="https://myidp.com/oauth2/v1/token"
    userinfoEndpoint="https://myidp.com/oauth2/v1/userinfo"
    jwksUri="https://myidp.com/oauth2/v1/keys"
    endSessionEndpoint="https://myidp.com/oauth2/v1/logout"
    customScope="openid, email, profile"
    prompt="login,consent"
    clientAuthentication="client_secret_basic"
    essentialAcrValues="phr"
    emailMapping="email"
    firstNameMapping="given_name"
    lastNameMapping="family_name"
    fullNameMapping="name"
    useFullName="false" />
</tsResponse>
Copy
{tsRequest:
}

Notes:

  • The response hides the client secret and replaces it with &lt;omit>.

  • You can use the testloginURL to validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.

Errors

HTTP status error Code Condition Details
400 400000 Bad Request The content of the request body is missing or incomplete, or contains malformed XML.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.

For more information, see Handling Errors.


Thanks for your feedback!Your feedback has been successfully submitted. Thank you!