docs: add Tableau docs for OIDC#4045
Conversation
Edit: OIDC & Tableau Cloud
QA: Update screenshots for Tableau OIDC integration guide
QA: Update screenshot annotations
nathan-contino
left a comment
nathan-contino
left a comment
There was a problem hiding this comment.
Initial feedback, looking pretty good but I have a few questions and suggestions.
|
|
||
| ## Overview | ||
|
|
||
| [Tableau](https://www.tableau.com/) is one of the most advanced data visualization tools used for business intelligence and data analysis. This document covers the configuration necessary to get Tableau Cloud working with FusionAuth as the identity provider. FusionAuth uses OpenID Connect (OIDC), allowing users to log in to your Tableau Cloud account using their FusionAuth credentials. |
There was a problem hiding this comment.
| [Tableau](https://www.tableau.com/) is one of the most advanced data visualization tools used for business intelligence and data analysis. This document covers the configuration necessary to get Tableau Cloud working with FusionAuth as the identity provider. FusionAuth uses OpenID Connect (OIDC), allowing users to log in to your Tableau Cloud account using their FusionAuth credentials. | |
| This page explains how to use FusionAuth as an identity provider for [Tableau Cloud](https://www.tableau.com/products/cloud-bi) using OpenID Connect (OIDC). |
Suggestion: remove 'most advanced' subjective phrasing, shorten and simplify this section for readability
|
|
||
| ### Prerequisites | ||
|
|
||
| This document assumes you have a running instance of FusionAuth and a working Tableau Cloud application. You also need admin accounts for both to configure them correctly. |
There was a problem hiding this comment.
| This document assumes you have a running instance of FusionAuth and a working Tableau Cloud application. You also need admin accounts for both to configure them correctly. | |
| This document assumes you have: | |
| * admin access to an instance of FusionAuth | |
| * admin access to a Tableau Cloud application |
Suggestion: present prerequisites as bullet points for scannability
|
|
||
| This document assumes you have a running instance of FusionAuth and a working Tableau Cloud application. You also need admin accounts for both to configure them correctly. | ||
|
|
||
| Finally, you need a FusionAuth user that you will use to sign into Tableau. You can use an existing user or create a new user for this purpose. |
There was a problem hiding this comment.
I'm not sure this is a prerequisite, since readers (should probably?) create a new user for this. I'd recommend removing this here and incorporating 'creating a new user for this purpose' into the flow below.
|
|
||
| ## Create an RS256 Signing Key | ||
|
|
||
| Tableau Cloud only supports the RS256 algorithm for signing tokens. Using ES256 or HS256 causes authentication to fail. Tableau Cloud specifically requires RSA signatures with SHA-256. Other algorithms like ES256 (ECDSA) and HS256 (HMAC) are not supported. |
There was a problem hiding this comment.
| Tableau Cloud only supports the RS256 algorithm for signing tokens. Using ES256 or HS256 causes authentication to fail. Tableau Cloud specifically requires RSA signatures with SHA-256. Other algorithms like ES256 (ECDSA) and HS256 (HMAC) are not supported. | |
| Tableau Cloud requires the RS256 algorithm for signing tokens, and RSA signatures with SHA-256. If you use any other algorithm, authentication will fail. |
Suggestion: simplify this instruction by naming only the supported configuration, instead of mentioning unsupported options.
|
|
||
| ## Create an Application | ||
|
|
||
| In your FusionAuth dashboard, navigate to <Breadcrumb>Applications</Breadcrumb> in the sidebar, then click the **➕** button in the top right to create a new application. Give it a memorable name, such as `Tableau Cloud OIDC`, and set the tenant you want to use. |
There was a problem hiding this comment.
| In your FusionAuth dashboard, navigate to <Breadcrumb>Applications</Breadcrumb> in the sidebar, then click the **➕** button in the top right to create a new application. Give it a memorable name, such as `Tableau Cloud OIDC`, and set the tenant you want to use. | |
| In your FusionAuth dashboard, navigate to <Breadcrumb>Applications</Breadcrumb> in the sidebar, then click the <InlineUIElement>+</InlineUIElement> button in the top right to create a new application. Give it a memorable name, such as `Tableau Cloud OIDC`, and set the tenant you want to use. |
Very nitpicky of me, maybe emojis aren't supported in inline ui elements and I just haven't experienced this yet?
| - **<InlineField>Client ID</InlineField>:** Enter the <InlineField>Client Id</InlineField> you copied from FusionAuth. | ||
| - **<InlineField>Client Secret</InlineField>:** Enter the <InlineField>Client secret</InlineField> you copied from FusionAuth. | ||
| - **<InlineField>Configuration URL</InlineField>:** Enter the <InlineField>OpenID Connect Discovery</InlineField> URL from the FusionAuth application. |
There was a problem hiding this comment.
| - **<InlineField>Client ID</InlineField>:** Enter the <InlineField>Client Id</InlineField> you copied from FusionAuth. | |
| - **<InlineField>Client Secret</InlineField>:** Enter the <InlineField>Client secret</InlineField> you copied from FusionAuth. | |
| - **<InlineField>Configuration URL</InlineField>:** Enter the <InlineField>OpenID Connect Discovery</InlineField> URL from the FusionAuth application. | |
| * <InlineField>Client ID</InlineField>: Enter the <InlineField>Client Id</InlineField> you copied from FusionAuth. | |
| * <InlineField>Client Secret</InlineField>: Enter the <InlineField>Client secret</InlineField> you copied from FusionAuth. | |
| * <InlineField>Configuration URL</InlineField>: Enter the <InlineField>OpenID Connect Discovery</InlineField> URL from the FusionAuth application. |
nitpicks: (all of these also apply to several other sections of this PR) I wouldn't bolden inlinefield elements. We should use asterisks for bullet points for consistency with the rest of the docs. When we do bold a term, we shouldn't bold the colon following the term.
|
|
||
| ## Add a New User | ||
|
|
||
| In your Tableau Cloud account, navigate to <Breadcrumb>Users</Breadcrumb> in the sidebar. Click the <InlineUIElement>Add Users</InlineUIElement> dropdown and select <InlineUIElement>Add Users by Username</InlineUIElement>. Tableau supports SCIM for automated provisioning, as does FusionAuth, but that is beyond the scope of this document. You must provide the same email addresses they use to log in to your FusionAuth instance. |
There was a problem hiding this comment.
| In your Tableau Cloud account, navigate to <Breadcrumb>Users</Breadcrumb> in the sidebar. Click the <InlineUIElement>Add Users</InlineUIElement> dropdown and select <InlineUIElement>Add Users by Username</InlineUIElement>. Tableau supports SCIM for automated provisioning, as does FusionAuth, but that is beyond the scope of this document. You must provide the same email addresses they use to log in to your FusionAuth instance. | |
| In your Tableau Cloud account, navigate to <Breadcrumb>Users</Breadcrumb> in the sidebar. Click the <InlineUIElement>Add Users</InlineUIElement> dropdown and select <InlineUIElement>Add Users by Username</InlineUIElement>. You must provide the same email addresses they use to log in to your FusionAuth instance. |
Personally I don't think this is worth calling out inline like this if we aren't going to explain how to implement it.
There was a problem hiding this comment.
The pronoun "they" comes out of nowhere in this section, and I'm not sure who you're referring to. Users, I think? We should avoid using pronouns this way, preferring to be explicit whenever possible and non-tedious. You might need to change the phrasing a bit since "Users use" is kind of awkward.
|
|
||
| In your Tableau Cloud account, navigate to <Breadcrumb>Users</Breadcrumb> in the sidebar. Click the <InlineUIElement>Add Users</InlineUIElement> dropdown and select <InlineUIElement>Add Users by Username</InlineUIElement>. Tableau supports SCIM for automated provisioning, as does FusionAuth, but that is beyond the scope of this document. You must provide the same email addresses they use to log in to your FusionAuth instance. | ||
|
|
||
| After doing so, they should receive an email with a link to the login page. When browsing to that page, they should enter their email address. |
There was a problem hiding this comment.
| After doing so, they should receive an email with a link to the login page. When browsing to that page, they should enter their email address. | |
| Now, users should receive an email with a link to the login page. When browsing to that page, they should enter their email address. |
I'm not sure what "After doing so" means in this context -- does it refer to the administrator action of configuring this, or the user action of creating an account? We should be more explicit if this is important.
Additionally, switched "they" to "user" to be explicit.
|
|
||
| <img src="/img/docs/lifecycle/authenticate-users/integrations/oidc/tableau/adding-user.png" alt="Adding a user via email address." width="1200" /> | ||
|
|
||
| They are redirected to the FusionAuth login screen when they click <InlineUIElement>Sign in</InlineUIElement>. There, they should fill in the credentials for their FusionAuth account. After they authenticate successfully, they are sent to the Tableau Cloud dashboard. |
There was a problem hiding this comment.
This paragraph feels a bit repetitive after the "After doing so..." paragraph above. Maybe we can remove one of them?
Apply feedback from FusionAuth
5 participants
#3935