Registrare EAS per abilitare SSO per il contenuto incorporato

In qualità di amministratore di Tableau Server, puoi registrare un server di autorizzazione esterno (EAS) per stabilire una relazione di trust tra Tableau Server e EAS utilizzando il protocollo standard OAuth 2.0. Stabilendo una relazione di trust, puoi:

  • Fornire ai tuoi utenti un’esperienza Single Sign-On (SSO) ai contenuti di Tableau incorporati nelle applicazioni personalizzate tramite il fornitore di identità (IdP) che hai già configurato per Tableau Server.
  • Autorizzare programmaticamente l’accesso all’API REST di Tableau (e all’API dei metadati a partire da Tableau Server di ottobre 2023) per conto degli utenti utilizzando un token Web JSON (JWT)

Quando il contenuto di Tableau incorporato viene caricato nell’applicazione esterna, viene utilizzato un flusso OAuth standard. Dopo che gli utenti effettuano correttamente l’accesso all’IdP, l’accesso a Tableau Server è automatico. Esegui la procedura descritta di seguito per registrare l’EAS con Tableau Server.

Importante:

  • alcune delle procedure in questo argomento richiedono la configurazione con software e servizi di terze parti. Abbiamo fatto del nostro meglio per verificare le procedure necessarie per abilitare la funzionalità EAS in Tableau Server. Tuttavia, il software e i servizi di terze parti potrebbero cambiare o la tua organizzazione potrebbe essere diversa. In caso di problemi, fai riferimento alla documentazione di terze parti per i dettagli della configurazione e il supporto.
  • Per abilitare l’incorporamento tramite EAS, Tableau Server deve essere configurato per l’utilizzo di SSL per il traffico HTTP.
  • Affinché il token di sessione sia valido, gli orologi dell’applicazione esterna e del server che ospita l’applicazione esterna devono essere impostati su UTC (tempo coordinato universale). Se uno degli orologi utilizza uno standard diverso, l’app connessa non verrà considerata attendibile.

Fase 1. Prima di iniziare

Per registrare un EAS con Tableau Server , devi disporre di un EAS già configurato. Inoltre, l’EAS deve inviare un token JWT (JSON Web Token) valido che contenga le attestazioni registrate e l’intestazione elencate nella tabella seguente.

AttestazioneNomeDescrizione o valore richiesto
"kid"ID chiaveObbligatorio (nell’intestazione). Identificatore di chiave univoco restituito dal provider di identità.
"iss"Rilasciato daObbligatorio (nell’intestazione o come attestazione). URI dell’emittente univoco che identifica l’app connessa attendibile e la relativa chiave di firma.
"alg"AlgoritmoObbligatorio (nell’intestazione). Algoritmo di firma JWT. I nomi degli algoritmi supportati sono elencati nella pagina Class JWSAlgorithm(Il collegamento viene aperto in una nuova finestra) della documentazione javadoc.io. L’algoritmo di firma può essere configurato utilizzando il comando descritto in vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms.
"sub"OggettoNome utente dell’utente autenticato di Tableau Server.
"aud"Destinatari

Il valore deve essere: "tableau"

"exp"Ora di scadenzaUn token JWT valido non deve essere scaduto. L’ora di scadenza del token JWT (in UTC) deve rientrare nel periodo di validità massimo configurato. Il periodo di validità massimo può essere configurato utilizzando il comando vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes.
"jti"ID JWTL’attestazione ID JWT fornisce un identificatore univoco per il token JWT, applicando la distinzione tra maiuscole e minuscole.
"scp"Ambito

Per l’incorporamento di flussi di lavoro, i valori supportati includono:

"tableau:views:embed"
"tableau:views:embed_authoring" (Aggiunto in Tableau Server 2022.3)
"tableau:metrics:embed” (ritirato in Tableau Server 2023.3)
"tableau:ask_data:embed" (aggiunto in Tableau Server 2023.1.verrà ritirato in Tableau Server 2024.2)

Note:

  • I valori devono essere passati come tipo di elenco.
  • Per tableau:views:embed, l’ambito rispetta le autorizzazioni degli utenti già configurate in Tableau Server e consente agli utenti di interagire con gli strumenti nella vista incorporata, se disponibili nella vista originale.
  • È consigliabile che il codice di incorporamento escluda il parametro toolbar. Per maggiori informazioni, consulta Problemi noti (solo incorporamento di flussi di lavoro) di seguito.

Per i workflow di autorizzazione dell’API REST, consulta Metodi API REST che supportano l’autorizzazione JWT.

Per i flussi di lavoro dell’API dei metadati che utilizzano l’API REST per l’autenticazione, l’unico ambito supportato è tableau:content:read.

Nota: le attestazioni JWT precedenti sono documentate nella sezione Registered Claim Names(Il collegamento viene aperto in una nuova finestra) della documentazione distribuita dall’organizzazione Internet Engineering Task Force (IETF).

Fase 2. Registrare l’EAS con Tableau Server

Registrando l’EAS con Tableau Server, stabilisci una relazione di trust tra EAS e Tableau Server . Ciò significa che quando gli utenti accedono ai contenuti di Tableau incorporati nella tua applicazione esterna, vengono reindirizzati per l’autenticazione con l’IdP. L’EAS genera il token di autenticazione, che viene passato a Tableau Server per la verifica. Dopo che la relazione di attendibilità è stata verificata, agli utenti viene concesso l’accesso al contenuto incorporato.

Dopo la registrazione dell’EAS, la relazione di trust stabilita si applica a tutti i siti in Tableau Server.

Nota: alcuni EAS supportano la possibilità di visualizzare una finestra di dialogo di consenso, che richiede l’approvazione degli utenti affinché l’applicazione acceda ai contenuti di Tableau. Per garantire un’esperienza ottimale per gli utenti, è consigliabile configurare l’EAS in modo che acconsenta automaticamente alla richiesta dell’applicazione esterna per conto degli utenti.

  1. Come amministratore di Tableau Server, accedi all’interfaccia utente Web di Tableau Services Manager (TSM). Per maggiori informazioni, consulta Accedere all’interfaccia utente Web di Tableau Services Manager.

  2. Passa a Identità e accesso utente > Server di autorizzazione e procedi come segue:
    1. Seleziona la casella di controllo Abilita accesso OAuth per il contenuto incorporato.

    2. Nella casella di testo URL emittente incolla l’URL dell’emittente dell’EAS.

    3. Fai clic sul pulsante Salva modifiche in sospeso.

  3. Al termine, effettua le seguenti operazioni:
    1. Nell’angolo superiore destro della pagina fai clic sul pulsante Modifiche in sospeso.

    2. Nell’angolo inferiore destro della pagina fai clic sul pulsante Applica modifiche e riavvia per arrestare e riavviare Tableau Server.

  1. Apri un prompt dei comandi come amministratore sul nodo iniziale (in cui è installato TSM) del cluster.
  2. Esegui questi comandi:

    tsm configuration set -k vizportal.oauth.external_authorization.enabled -v true
    tsm configuration set -k vizportal.oauth.external_authorization_server.issuer -v "<issuer_url_of_EAS>"
    tsm restart

Fase 3. Fasi successive

Per l’incorporamento di flussi di lavoro

Dopo aver configurato Tableau Server per l’utilizzo dell’EAS, devi aggiungere il codice di incorporamento alla tua applicazione esterna. Assicurati di includere il token JWT valido generato dall’EAS, come descritto nella Fase 1, nel componente web chiamato dall’applicazione esterna.

Per maggiori informazioni sull’incorporamento del contenuto di Tableau, consulta uno o entrambi i seguenti argomenti:

Nota: affinché gli utenti possano eseguire correttamente l’autenticazione quando accedono ai contenuti incorporati, i browser devono essere configurati in modo da consentire i cookie di terze parti.

Controllare dove possono essere incorporati i contenuti utilizzando l’elenco consentiti di dominio per l’incorporamento

A partire da Tableau Server 2023.3, tu e i tuoi utenti potete controllare se i contenuti di Tableau possono essere incorporati senza restrizioni o limitati a determinati domini utilizzando il metodo Aggiorna impostazioni di incorporamento per il sito nell’API REST di Tableau.

Per impostazione predefinita, l’impostazione del sito per l’incorporamento unrestrictedEmbedding è impostata su true per consentire l’incorporamento senza restrizioni. In alternativa, tu e i tuoi utenti potete configurare l’impostazione su false e specificare i domini in cui possono essere incorporati i contenuti di Tableau nelle applicazioni esterne utilizzando il parametro allowList.

Per maggiori informazioni, consulta uno o entrambi i seguenti argomenti:

Per i workflow di autorizzazione dell’API REST

Dopo che il token JWT è stato configurato, è necessario aggiungere il token JWT valido alla richiesta di accesso all’API REST per l’accesso autorizzato. Per maggiori informazioni, consulta Ambiti di accesso per le app connesse.

Per i flussi di lavoro dell’API dei metadati

Dopo averlo configurato, devi aggiungere il token JWT valido alla richiesta di accesso all’API REST. Per maggiori informazioni, consulta Ambiti di accesso per le app connesse.

Problemi noti (solo incorporamento di flussi di lavoro)

Esistono alcuni problemi noti per l’utilizzo delle app connesse che verranno risolti in una versione futura.

  • Funzionalità della barra degli strumenti: quando per il contenuto incorporato è definito il parametro toolbar, non tutte le funzionalità della barra degli strumenti funzioneranno. Per risolvere il problema, è consigliabile nascondere il parametro toolbar come nell’esempio seguente.

    <tableau-viz id='tab-viz' src='https://<your_server>/t/<your_site>/...'
    	toolbar='hidden'>
    </tableau-viz>

  • Origini dati pubblicate: le origini dati pubblicate impostate su Avvisa utente per le credenziali del database non verranno visualizzate. Per risolvere il problema, se possibile, è consigliabile che i proprietari delle origini dati incorporino le proprie credenziali del database.

Risoluzione dei problemi

Quando il contenuto incorporato non viene visualizzato nell’applicazione esterna o l’autorizzazione API REST Tableau non riesce, puoi utilizzare gli strumenti per sviluppatori di un browser per ispezionare e identificare i codici di errore che potrebbero essere associati alla funzionalità EAS abilitata nel Tableau Server.

Fai riferimento alla tabella seguente per consultare la descrizione del codice di errore e la potenziale risoluzione.

Codice di erroreRiepilogoDescrizionePotenziale risoluzione o spiegazione
5SYSTEM_USER_NOT_FOUNDImpossibile trovare l’utente di Tableau
Per risolvere questo problema, verifica che il valore dell’attestazione "sub" (Soggetto) in JWT sia "username" per Tableau Server autenticato. Questo valore distingue tra maiuscole e minuscole.
16LOGIN_FAILEDAccesso non riuscitoQuesto errore è in genere causato da uno dei seguenti problemi di attestazione nel token JWT:
67FEATURE_NOT_ENABLEDL’accesso su richiesta non è supportatoL’accesso su richiesta è disponibile solo tramite i siti Tableau Cloud con licenza.
10081COULD_NOT_RETRIEVE_IDP_METADATAEndpoint dei metadati EAS mancantePer risolvere questo problema, verifica che l’EAS sia configurato correttamente e che venga chiamato l’emittente corretto.
10082AUTHORIZATION_SERVER_ISSUER_NOT_SPECIFIEDEmittente mancantePer risolvere questo problema, verifica che venga chiamato l’emittente corretto. Per modificare l’URL dell’emittente, puoi utilizzare il comando vizportal.oauth.external_authorization_server.issuer.
10083BAD_JWTL’intestazione JWT presenta problemiLe attestazioni "kid" (ID del segreto) o "clientId" (Emittente) non sono presenti nell’intestazione JWT. Per risolvere questo problema, assicurati che queste informazioni siano incluse.
10084JWT_PARSE_ERRORIl token JWT presenta problemiPer risolvere il problema, verifica quanto segue:
  • Il valore "aud" (Destinatari) a cui viene fatto riferimento nel token JWT utilizza il valore "tableau". Questo valore distingue tra maiuscole e minuscole.
  • I valori "aud" (Destinatari) e "sub" (Soggetto) sono inclusi nel JWT.
10085COULD_NOT_FETCH_JWT_KEYSJWT non è riuscito a trovare le chiaviImpossibile trovare il segreto.

Per risolvere questo problema, verifica che venga chiamato l’emittente corretto. Per modificare l’URL dell’emittente, puoi utilizzare il comando vizportal.oauth.external_authorization_server.issuer.

10087BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGNProblema dell’algoritmo di firma JWTPer risolvere il problema, puoi rimuovere l’algoritmo di firma. Per maggiori informazioni, consulta vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms.
10088RSA_KEY_SIZE_INVALIDProblema dei requisiti di firma JWTPer risolvere questo problema, verifica con l’EAS o l’IdP che il token JWT sia firmato con una chiave RSA di 2048.
10091JTI_ALREADY_USEDJWT univoco richiestoIl token JWT è già stato utilizzato nel processo di autenticazione. Per risolvere questo problema, l’EAS o l’IdP deve generare un nuovo token JWT.
10092NOT_IN_DOMAIN_ALLOW_LISTIl dominio del contenuto incorporato non è specificatoPer risolvere questo problema, assicurati che l’impostazione unrestrictedEmbedding sia configurata su true o che il parametro domainAllowlist includa i domini in cui è incorporato il contenuto di Tableau utilizzando il metodo Aggiorna le impostazioni di incorporamento per il sito(Il collegamento viene aperto in una nuova finestra) nell’API REST di Tableau.
10094MISSING_REQUIRED_JTIID JWT mancantePer risolvere questo problema, verifica che "jti" (ID JWT) sia incluso nel JWT.
10096JWT_EXPIRATION_EXCEEDS_CONFIGURED_EXPIRATION_PERIOD Il valore "exp" (Ora di scadenza) è superiore al periodo di validità massimo predefinito. Per risolvere questo problema, esamina le attestazioni registrate(Il collegamento viene aperto in una nuova finestra) richieste per un token JWT valido e assicurati che venga utilizzato il valore corretto. Per modificare il periodo di validità massimo, puoi utilizzare il comando vizportal.oauth.external_authorization_server.max_expiration_period_in_minutes.
10097SCOPES_MALFORMEDProblemi con l’attestazione relativa agli ambitiQuesto errore può verificarsi quando l’attestazione "scp" (Ambito) non è presente nel JWT o non è passata come tipo di elenco. Per risolvere questo problema, verifica che "scp" sia incluso nel JWT e passato come tipo di elenco. Per informazioni sulla risoluzione dei problemi con un JWT, consulta Debugger(Il collegamento viene aperto in una nuova finestra) sul sito auth0.
10098JWT_UNSIGNED_OR_ENCRYPTEDIl token JWT non è firmato o è crittografatoTableau non supporta i token JWT non firmati o crittografati.
10099SCOPES_MISSING_IN_JWTAttestazione mancante per gli ambitiNel token JWT manca l’attestazione "scp" (Ambito) richiesta. Per risolvere questo problema, verifica che "scp" sia incluso nel JWT. Per informazioni sulla risoluzione dei problemi con un JWT, consulta Debugger(Il collegamento viene aperto in una nuova finestra) sul sito auth0.
10100JTI_PERSISTENCE_FAILEDErrore ID JWT imprevistoSi è verificato un errore imprevisto con "jti" (ID JWT). Per risolvere questo problema, è necessario generare un nuovo token JWT con un nuovo "jti".
10103JWT_MAX_SIZE_EXCEEDEDJWT supera la dimensione massimaQuesto errore può verificarsi quando la dimensione del token JWT è superiore a 8.000 byte. Per risolvere questo problema, assicurati che vengano passate a Tableau Server solo le attestazioni necessarie.
Grazie per il tuo feedback.Il tuo feedback è stato inviato. Grazie!