Configurare le app connesse con trust OAuth 2.0

In qualità di amministratore del sito Tableau Cloud, puoi registrare un server di autorizzazione esterno (EAS) per stabilire una relazione di trust tra il tuo sito Tableau Cloud 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 esterne tramite il fornitore di identità (IdP) che hai già configurato per il tuo sito Tableau Cloud.
  • Autorizzare programmaticamente l’accesso all’API REST di Tableau (e all’API dei metadati a partire da Tableau Cloud 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 Cloud è automatico. Esegui la procedura descritta di seguito per registrare l’EAS con il tuo sito Tableau Cloud.

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 Cloud. 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.
  • 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 il tuo sito Tableau Cloud , 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, in HTTPS, 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.
"sub"OggettoNome utente (indirizzo e-mail) dell’utente autenticato di Tableau Cloud.
"aud"Destinatari

Il valore deve essere: "tableau:<site_luid>"

Per ottenere il LUID del sito, puoi utilizzare il metodo di accesso dell’API REST di Tableau o seguire i passaggi seguenti per copiare l’ID del sito. Nota: per poter copiare il ID del sito devi registrare un EAS utilizzando la procedura qui descritta.

  1. Seleziona Impostazioni > App connesse, quindi seleziona l’app collegata al server di autorizzazione esterno.
  2. Fai clic sul pulsante Copia ID sito.

"exp"Ora di scadenza

Un token JWT valido non deve essere scaduto. L’ora di scadenza (in UTC) del token JWT deve rientrare nel periodo di validità massimo, che è di 10 minuti.

"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"
"tableau:metrics:embed” (ritirato a ottobre 2023 in Tableau 2023.3)
"tableau:ask_data:embed" (ritirato a febbraio 2024 in Tableau 2024.1)

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

https://tableau.com/odaAccesso su richiesta - attestazione (abilita la funzionalità)Solo per l’incorporamento di flussi di lavoro.

Il valore deve essere "true" e devono essere specificati uno o più gruppi di Tableau Cloud (vedi la riga seguente). Per maggiori informazioni, consulta la sezione Accesso su richiesta (solo incorporamento di flussi di lavoro) di seguito.

https://tableau.com/groupsAccesso su richiesta - attestazione (specifica il nome del gruppo)Solo per l’incorporamento di flussi di lavoro.

Il valore deve corrispondere al nome di uno o più gruppi di Tableau Cloud. Per maggiori informazioni, consulta la sezione Accesso su richiesta (solo incorporamento di flussi di lavoro) di seguito.

(Attributi utente)(Valori degli attributi utente)

Solo per l’incorporamento di flussi di lavoro.

Puoi includere gli attributi utente in JWT. Quindi, quando le funzioni degli attributi utente vengono utilizzate in contenuti incorporati, Tableau controlla il contesto dell’utente autenticato e determina quali dati possono essere visualizzati in fase di esecuzione.

Note:

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 Cloud

Registrando l’EAS con Tableau Cloud, stabilisci una relazione di trust tra EAS e il tuo sito Tableau Cloud . 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 Cloud per la verifica. Dopo che la relazione di attendibilità è stata verificata, agli utenti viene concesso l’accesso al contenuto incorporato.

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. In qualità di amministratore del sito, accedi a Tableau Cloud.

  2. Dal riquadro di sinistra seleziona Impostazioni > App connesse.

  3. Fai clic sulla freccia rivolta verso il basso del pulsante Nuova app connessa e seleziona Trust OAuth 2.0.

  4. Nella finestra di dialogo Crea app connessa procedi come segue:
    1. Nella casella di testo Nome inserisci un nome per l’app connessa.

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

    3. Seleziona Abilita app connessa. Per motivi di sicurezza, un’app connessa è disabilitata per impostazione predefinita quando viene creata.

    4. Al termine, fai clic sul pulsante Crea.

  5. Dopo aver creato l’applicazione connessa, copia l’ID del relativo sito. L’ID del sito viene utilizzato per l’attestazione "aud" (Destinatari) del JWT descritta nella fase 1 precedente.

Fase 3. Fasi successive

Per l’incorporamento di flussi di lavoro

Dopo aver configurato il tuo sito Tableau Cloud 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 giugno 2023 (Tableau 2023.2), 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.

Accesso su richiesta (solo incorporamento di flussi di lavoro)

A partire da ottobre 2023, se il tuo sito è concesso in licenza con il modello basato sull’utilizzo di Analisi incorporata(Il collegamento viene aperto in una nuova finestra), puoi estendere a più utenti l’accesso al contenuto di Tableau incorporato utilizzando l’accesso su richiesta. Con l’accesso su richiesta, consenti ai tuoi utenti di interagire con il contenuto di Tableau incorporato autenticato tramite l’app connessa senza dover effettuare il provisioning di tali utenti nel tuo sito Tableau Cloud. L’accesso su richiesta elimina la necessità di aggiungere e gestire gli utenti in Tableau Cloud per supportare l’accesso al contenuto incorporato.

Come funziona l’accesso su richiesta

L’accesso al contenuto di Tableau incorporato tramite l’accesso su richiesta è determinato dalle autorizzazioni a livello di gruppo ereditate (ad esempio, a livello di progetto) o applicate direttamente al contenuto. Gli utenti come amministratori del sito, proprietari o responsabili di progetto e proprietari dei contenuti possono assegnare le autorizzazioni a livello di gruppo per il contenuto. Quando gli utenti accedono al contenuto incorporato abilitato tramite la funzionalità di accesso su richiesta, Tableau verifica che il token JWT contenga le attestazioni di appartenenza al gruppo corrette prima di visualizzare il contenuto.

Prerequisiti

I seguenti criteri devono essere soddisfatti per consentire l’accesso su richiesta al contenuto incorporato:

  1. Il sito è concesso in licenza con il modello basato sull’utilizzo di Analisi incorporata(Il collegamento viene aperto in una nuova finestra)
  2. Per il gruppo è stata abilitata la funzionalità di accesso su richiesta
  3. Per il contenuto di Tableau sono state specificate le autorizzazioni di gruppo
  4. È stata creata l’app connessa di Tableau
  5. Il token JWT utilizzato dall’app connessa include le attestazioni https://tableau.com/oda e https://tableau.com/groups
  6. Il contenuto di Tableau è incorporato in un’applicazione esterna

Quando questi criteri sono soddisfatti, gli utenti possono interagire con il contenuto di Tableau incorporato abilitato tramite la funzionalità di accesso su richiesta.

Abilitare la funzionalità di accesso su richiesta

Per abilitare la funzionalità di accesso su richiesta per un gruppo, quando si crea o si modifica un gruppo, è necessario selezionare la casella di controllo Consenti accesso su richiesta. Per maggiori informazioni sulla creazione dei gruppi, consulta Creare un gruppo e aggiungere gli utenti.

Puoi anche abilitare questa funzionalità tramite l’API REST di Tableau. Per maggiori informazioni, consulta i metodi Crea gruppo(Il collegamento viene aperto in una nuova finestra) e Aggiorna gruppo(Il collegamento viene aperto in una nuova finestra) nella Guida dell’API REST di Tableau.

Funzionalità quando è abilitato l’accesso su richiesta

Gli utenti che accedono al contenuto di Tableau incorporato dispongono delle funzionalità(Il collegamento viene aperto in una nuova finestra) Visualizza per il contenuto. Gli utenti dispongono delle funzionalità Visualizza indipendentemente dal modello selezionato o dalle funzionalità personalizzate che potrebbero essere configurate per il gruppo (ad esempio, un utente con il ruolo Viewer non sarà mai in grado di scaricare un’origine dati, anche se tale funzionalità gli viene esplicitamente concessa per un’origine dati specifica).

Monitorare l’accesso su richiesta

Se disponi di Tableau Cloud con Advanced Management(Il collegamento viene aperto in una nuova finestra), puoi utilizzare il log attività per monitorare l’utilizzo dell’accesso su richiesta. Gli eventi nel log attività che acquisiscono l’accesso su richiesta includono, a titolo esemplificativo, accesso alla vista e accesso. Per maggiori informazioni su questi eventi, consulta Riferimento del tipo di evento del log attività.

Limitazioni

Poiché i flussi di lavoro per l’accesso su richiesta consentono a determinati utenti che accedono al contenuto di Tableau incorporato di essere anonimi e temporanei in Tableau Cloud, le seguenti funzionalità non sono disponibili per gli utenti che accedono al contenuto incorporato abilitato tramite la funzionalità di accesso su richiesta:

  • Creazione di viste personalizzate
  • Condivisione del contenuto tramite il pulsante di condivisione del contenuto
  • Sottoscrizione di contenuto per ricevere snapshot delle informazioni tramite e-mail

Nota: a partire da febbraio 2024 (Tableau 2024.1), le richieste dell’API REST di Tableau possono essere effettuate come utente con accesso su richiesta.

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://online.tableau.com/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 tuo sito Tableau Cloud.

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 TableauPer risolvere questo problema, verifica che il valore dell’attestazione "sub" (Soggetto) nel token JWT sia il nome utente (indirizzo e-mail) dell’utente autenticato di Tableau Cloud. 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:
  • 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 il valore corretto non sia superiore a 10 minuti.
  • Il valore "sub" (Soggetto) sta chiamando un utente sconosciuto. Per risolvere questo problema, verifica che il valore "sub" sia il nome utente (indirizzo e-mail) dell’utente autenticato di Tableau Cloud.
67FEATURE_NOT_ENABLEDL’accesso su richiesta non è supportatoL’accesso su richiesta è disponibile solo tramite i siti Tableau Cloud con licenza.
142EXTERNAL_AUTHORIZATION_SERVER_NOT_FOUNDEAS non trovatoPer risolvere questo problema, verifica che venga chiamato l’emittente corretto.
143EXTERNAL_AUTHORIZATION_SERVER_LIMIT_EXCEEDEDLimite EAS superatoIl sito ha raggiunto il numero massimo consentito (1) di server di autorizzazione esterni (EAS) registrati.
144INVALID_ISSUER_URLURL dell’emittente non valido L’URL dell’emittente non è valido o l’attributo "iss" (issuer) non è presente nel JWT.
149EAS_INVALID_JWKS_URIURI JWKS mancanteL’URI JWKS non esiste nei metadati IdP o l’URI JWKS non è configurato in Tableau. Per risolvere questo problema, configura un URI JWKS valido.
150EAS_RETRIEVE_JWK_SOURCE_FAILEDErrore nel recupero dell’origine della chiavePer risolvere questo problema, verifica che l’URI JWKS sia configurato correttamente.
151EAS_RETRIEVE_METADATA_FAILEDErrore nel recupero dei metadati da issuerUrlPer risolvere questo problema, verifica che l’URI JWKS sia configurato correttamente.
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.
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.

10087BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGNProblema dell’algoritmo di firma JWTPer risolvere il problema, puoi rimuovere l’algoritmo di firma.
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.
10095EXTERNAL_AUTHZ_SERVER_DISABLEDEAS disabilitatoL’app connessa per l’EAS registrato nel sito è disabilitata.
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 il valore corretto non sia superiore a 10 minuti.
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".
10101EPHEMERAL_USER_LOGIN_FAILED_SITE_NOT_UBP_ENABLEDL’accesso su richiesta non è supportatoIl sito non dispone della licenza con il modello basato sull’utilizzo per l’analisi incorporata necessario per abilitare l’accesso su richiesta. Per maggiori informazioni sulle licenze, consulta Informazioni sui modelli di licenza.
10102EPHEMERAL_USER_NOT_SUPPORTEDL’accesso su richiesta non è supportato quando l’attributo iframe-auth è abilitatoQuesto errore può verificarsi quando l’attributo iframe-auth è abilitato. Per risolvere questo problema, verifica che venga utilizzata l’API di incorporamento di Tableau versione 3.6 o successiva.
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 Cloud solo le attestazioni necessarie.
Grazie per il tuo feedback.Il tuo feedback è stato inviato. Grazie!