Configurare le app connesse con Trust OAuth 2.0

Applicabile a: Tableau Cloud, Tableau Server

In qualità di amministratore di Tableau Server, puoi registrare uno o più server di autorizzazione esterni (EAS) per stabilire una relazione di trust tra Tableau Server e EAS utilizzando il protocollo standard OAuth 2.0.

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.

Come funzionano le app connesse di Tableau con il trust OAuth 2.0

La relazione di trust tra il tuo sito Tableau Server e l'applicazione esterna vengono stabiliti e verificati tramite un token di autenticazione nello standard JSON Web Token (JWT).

Quando il contenuto di Tableau incorporato viene caricato nell’applicazione esterna, viene utilizzato un flusso OAuth, Authorization Code Flow. 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 .

Componenti principali di un’app connessa

I seguenti componenti dell’app connessa funzionano insieme al token JWT nell’applicazione esterna per autenticare gli utenti e visualizzare il contenuto incorporato.

Server di autorizzazione esterno (EAS): il server, in genere il tuo IdP, che funge da interfaccia tra l'utente e l'applicazione esterna. Il server autentica e autorizza l'accesso degli utenti ai contenuti protetti di Tableau.
URL dell'emittente: l'URL che identifica in modo univoco l'istanza EAS.

Flusso di lavoro dell’app connessa

Incorporamento di flussi di lavoro

Il diagramma seguente illustra come funziona l’autenticazione tra il server di autorizzazione esterno (EAS), l’applicazione esterna (server Web e pagina Web) e l’app connessa Tableau.

L’utente visita la pagina Web: quando un utente visita il contenuto incorporato in una pagina Web, la pagina Web invia una richiesta GET all’applicazione esterna.
L'applicazione esterna reindirizza la richiesta al server di autorizzazione esterno (EAS): l'applicazione esterna risponde con una pagina Web che reindirizza al server di autorizzazione esterno (EAS).
L'utente si autentica con il server di autorizzazione esterno (EAS): l'utente si autentica e ottiene l'autorizzazione tramite EAS.
Il server di autorizzazione esterno (EAS) risponde alla pagina web con il codice di autorizzazione: il server di autorizzazione esterno (EAS) risponde alla pagina con un codice di autorizzazione e reindirizza alla pagina Web.
Il server di autorizzazione esterno (EAS) converte il codice di autorizzazione in JWT: la pagina Web chiama l'EAS per convertire il codice di autorizzazione in un JWT, che la pagina Web inserisce nell'URL del contenuto incorporato.
La pagina Web richiede contenuti da Tableau: la pagina web carica l'iFrame e invia una richiesta GET a Tableau.
Tableau convalida il token: Tableau convalida il JWT nell'URL con la firma e risponde con il contenuto, rispettando gli ambiti di incorporamento definiti nel JWT.

Creare un’app connessa

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.

Attestazione	Nome	Descrizione o valore richiesto
"`kid`"	ID chiave	Obbligatorio (nell’intestazione). Identificatore di chiave univoco restituito dal provider di identità.
"`iss`"	Rilasciato da	Obbligatorio (nell’intestazione o come attestazione). URI dell’emittente univoco che identifica l’app connessa attendibile e la relativa chiave di firma.
"`alg`"	Algoritmo	Obbligatorio (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`"	Oggetto	Nome utente dell’utente autenticato di Tableau Server.
"`aud`"	Destinatari	Il valore deve essere: "`tableau`"
"`exp`"	Ora di scadenza	Un 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 JWT	L’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`.
`https://tableau.com/groups`	Appartenenza ai gruppi dinamica	Solo per l’incorporamento di flussi di lavoro. Il valore deve corrispondere al nome di uno o più gruppi di Tableau Server. Per maggiori informazioni, consulta la sezione Appartenenza ai gruppi dinamica (solo incorporamento di flussi di lavoro) di seguito.

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.

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.

Informazioni sull’EAS a livello di sito

A partire da Tableau Server 2024.2 puoi configurare l’EAS a livello di sito. Per registrare un EAS a livello di sito, le app connesse devono essere abilitate in Tableau Server Manager (TSM).

Esistono due modi per registrare l’EAS a livello di server: utilizzando l’interfaccia utente Web di TSM o utilizzando l’interfaccia della riga di comando TSM.

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

Opzione 1: utilizzo dell’interfaccia utente Web di TSM

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.
Esegui una di queste operazioni:
- In Tableau Server 2024.2 e versioni successive vai alla pagina Identità utente e accesso > scheda App connesse.
- In Tableau Server 2023.3 e versioni precedenti vai alla pagina Identità utente e accesso > scheda Server di autorizzazione.
Esegui una di queste operazioni:
- In Tableau Server 2024.2 e versioni successive:
  1. Seleziona la casella di controllo Abilita app connesse.
  2. Seleziona il secondo pulsante di opzione Consenti app connesse (configurazione a livello di sito) e trust OAuth 2.0 a livello di server (configurazione seguente).
  3. Nella casella di testo URL emittente incolla l’URL dell’emittente dell’EAS.
  4. Fai clic sul pulsante Salva modifiche in sospeso.
- In Tableau Server 2023.3 e versioni precedenti:
  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.
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.

Opzione 2: utilizzo dell’interfaccia della riga di comando TSM

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

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

A partire da Tableau Server 2024.2, puoi registrare uno o più EAS per un sito. Dopo aver registrato l’EAS a livello di sito, la relazione di trust stabilita si applica solo al sito.

Nota: un prerequisito per la configurazione dell’EAS a livello di sito prevede che le app connesse siano abilitate in TSM.

Fase 1: abilitare le app connesse

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.
Passa alla pagina Identità utente e accesso > scheda App connesse.
Seleziona la casella di controllo Abilita app connesse.
Esegui una di queste operazioni:
- Seleziona il primo pulsante di opzione, Consenti app connesse (configurazione a livello di sito) per abilitare la registrazione degli EAS solo a livello di sito.
- (Impostazione predefinita) Seleziona il secondo pulsante di opzione Consenti app connesse (configurazione a livello di sito) e trust OAuth 2.0 a livello di server (configurazione seguente) per abilitare la registrazione degli EAS sia a livello di sito che a livello di server. Se scegli questa opzione, assicurati che l’URL dell’emittente specificato a livello di sito sia diverso da quello a livello di server.
Fai clic sul pulsante Salva modifiche in sospeso.
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.

Fase 2: registrare l’EAS

In qualità di amministratore di Tableau Server, accedi a Tableau Server.
Dal riquadro di sinistra seleziona Impostazioni > App connesse.
Fai clic sulla freccia rivolta verso il basso del pulsante Nuova app connessa e seleziona Trust OAuth 2.0.
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.
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 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:

Incorpora le metriche. Consulta l’argomento Incorporare le metriche nelle pagine Web(Il collegamento viene aperto in una nuova finestra) nella Guida di Tableau. In Tableau Server 2023.3 è stata ritirata la possibilità di incorporare parametri.
Incorpora le viste e le metriche di Tableau utilizzando l’API di incorporamento Tableau v3(Il collegamento viene aperto in una nuova finestra).

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:

Aggiornare le impostazioni di incorporamento per il sito(Il collegamento viene aperto in una nuova finestra) nella Guida dell’API REST di Tableau
Impostazione del sito di Tableau per l’incorporamento(Il collegamento viene aperto in una nuova finestra) nella Guida dell’API di incorporamento v3 di Tableau.

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.

Gestire un’app connessa

Appartenenza ai gruppi dinamica (solo incorporamento di flussi di lavoro)

A partire da Tableau Server 2024.2, se sono configurate le app connesse e l’impostazione della funzionalità è abilitata, puoi controllare dinamicamente l’appartenenza ai gruppi tramite attestazioni personalizzate incluse nel token Web JSON inviato dall’applicazione esterna.

Una volta configurata, durante l’autenticazione degli utenti, l’applicazione esterna invia il token Web JSON che contiene due attestazioni personalizzate per l’appartenenza ai gruppi: gruppo (https://tableau.com/groups) e nomi di gruppo (ad esempio, “Gruppo1” e “Gruppo2”) in cui asserire l’utente. Tableau convalida il token Web JSON e quindi consente l’accesso ai gruppi e al contenuto le cui autorizzazioni dipendono da tali gruppi.

Per maggiori informazioni, consulta Appartenenza ai gruppi dinamica con le asserzioni.

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.
Viste incorporate su più siti: in Tableau Server 2023.1 e versioni precedenti, al passaggio da una vista all’altra su siti diversi nello stesso browser viene restituito un errore 1008: impossibile recuperare il segreto per l’app connessa. Per ovviare a questo problema, esegui l’upgrade a Tableau Server 2023.3 o versione successiva.

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 errore	Riepilogo	Descrizione	Potenziale risoluzione o spiegazione
5	SYSTEM_USER_NOT_FOUND	Impossibile 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.
16	LOGIN_FAILED	Accesso non riuscito	Questo 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 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. Il valore "`sub`" (Soggetto) sta chiamando un utente sconosciuto. Per risolvere questo problema, verifica che l’attestazione "`sub`" sia "username". Questo valore distingue tra maiuscole e minuscole.
67	FEATURE_NOT_ENABLED	L’accesso su richiesta non è supportato	L’accesso su richiesta è disponibile solo tramite i siti Tableau Cloud con licenza.
10081	COULD_NOT_RETRIEVE_IDP_METADATA	Endpoint dei metadati EAS mancante	Per risolvere questo problema, verifica che l’EAS sia configurato correttamente e che venga chiamato l’emittente corretto.
10082	AUTHORIZATION_SERVER_ISSUER_NOT_SPECIFIED	Emittente mancante	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.
10083	BAD_JWT	L’intestazione JWT presenta problemi	Le attestazioni "`kid`" (ID del segreto) o "`clientId`" (Emittente) non sono presenti nell’intestazione JWT. Per risolvere questo problema, assicurati che queste informazioni siano incluse.
10084	JWT_PARSE_ERROR	Il token JWT presenta problemi	Per 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.
10085	COULD_NOT_FETCH_JWT_KEYS	JWT non è riuscito a trovare le chiavi	Impossibile 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.
10087	BLOCKLISTED_JWS_ALGORITHM_USED_TO_SIGN	Problema dell’algoritmo di firma JWT	Per risolvere il problema, puoi rimuovere l’algoritmo di firma. Per maggiori informazioni, consulta vizportal.oauth.external_authorization_server.blocklisted_jws_algorithms.
10088	RSA_KEY_SIZE_INVALID	Problema dei requisiti di firma JWT	Per risolvere questo problema, verifica con l’EAS o l’IdP che il token JWT sia firmato con una chiave RSA di 2048.
10091	JTI_ALREADY_USED	JWT univoco richiesto	Il token JWT è già stato utilizzato nel processo di autenticazione. Per risolvere questo problema, l’EAS o l’IdP deve generare un nuovo token JWT.
10092	NOT_IN_DOMAIN_ALLOW_LIST	Il dominio del contenuto incorporato non è specificato	Per 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.
10094	MISSING_REQUIRED_JTI	ID JWT mancante	Per risolvere questo problema, verifica che "`jti`" (ID JWT) sia incluso nel JWT.
10096	JWT_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.
10097	SCOPES_MALFORMED	Problemi con l’attestazione relativa agli ambiti	Questo 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.
10098	JWT_UNSIGNED_OR_ENCRYPTED	Il token JWT non è firmato o è crittografato	Tableau non supporta i token JWT non firmati o crittografati.
10099	SCOPES_MISSING_IN_JWT	Attestazione mancante per gli ambiti	Nel 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.
10100	JTI_PERSISTENCE_FAILED	Errore ID JWT imprevisto	Si è verificato un errore imprevisto con "`jti`" (ID JWT). Per risolvere questo problema, è necessario generare un nuovo token JWT con un nuovo "`jti`".
10103	JWT_MAX_SIZE_EXCEEDED	JWT supera la dimensione massima	Questo 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.

Torna in alto

Grazie per il tuo feedback.

Il tuo feedback è stato inviato. Grazie!

Guida di Tableau Server su Windows