Incorpora i componenti visivi di Amazon Quick Sight nelle applicazioni Web utilizzando Amazon Cognito e l'automazione IAc - Prontuario AWS

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Incorpora i componenti visivi di Amazon Quick Sight nelle applicazioni Web utilizzando Amazon Cognito e l'automazione IAc

Ishita Gupta e Srishti Wadhwa, Amazon Web Services

Riepilogo

Questo modello offre un approccio specializzato per incorporare i componenti visivi di Amazon Quick Sight nelle applicazioni React utilizzando l'incorporamento di utenti registrati con l'autenticazione semplificata di Amazon Cognito. Queste risorse vengono quindi distribuite tramite un modello di infrastruttura come codice (IaC). A differenza del tradizionale incorporamento di dashboard, questa soluzione isola tabelle e grafici specifici per l'integrazione diretta nelle applicazioni React, il che migliora notevolmente sia le prestazioni che l'esperienza utente.

L'architettura stabilisce un flusso di autenticazione efficiente tra la gestione degli utenti di Amazon Cognito e le autorizzazioni Quick Sight: gli utenti si autenticano tramite Amazon Cognito e accedono alle visualizzazioni autorizzate in base alle regole di condivisione del dashboard in Quick Sight. Questo approccio semplificato elimina la necessità di un accesso diretto alla console Quick Sight, pur mantenendo solidi controlli di sicurezza.

L'ambiente completo viene distribuito tramite un unico AWS CloudFormation modello che fornisce tutti i componenti dell'infrastruttura necessari, tra cui:

  • Un backend serverless che utilizza Amazon API AWS Lambda Gateway

  • Hosting frontend sicuro tramite Amazon CloudFront, Amazon Simple Storage Service (Amazon S3) e AWS WAF

  • Gestione delle identità tramite Amazon Cognito

Tutti i componenti sono configurati seguendo le migliori pratiche di sicurezza con politiche, protezione e crittografia dei privilegi minimi AWS Identity and Access Management (IAM). AWS WAF end-to-end

Questa soluzione è ideale per i team di sviluppo e le organizzazioni che desiderano integrare analisi sicure e interattive nelle proprie applicazioni, mantenendo al contempo un controllo granulare sull'accesso degli utenti. La soluzione utilizza servizi AWS gestiti e automazione per semplificare il processo di integrazione, migliorare la sicurezza e garantire la scalabilità per soddisfare le esigenze aziendali in evoluzione.

Destinatari e casi d'uso:

  • Sviluppatori di frontend che desiderano incorporare l'analisi nelle app React

  • Team di prodotto Software as a Service (SaaS) che desiderano offrire visualizzazioni dei dati per utente o basate sui ruoli

  • Architetti di soluzioni interessati a integrare l'analisi in portali personalizzati AWS

  • Sviluppatori di business intelligence (BI) che desiderano esporre le immagini agli utenti autenticati senza richiedere l'accesso completo alla dashboard

  • Team aziendali che desiderano incorporare grafici Quick Sight interattivi negli strumenti interni

Prerequisiti e limitazioni

Prerequisiti

Per implementare con successo questo modello, assicurati che siano presenti le seguenti condizioni:

  • Attivo Account AWS: Account AWS con autorizzazioni per distribuire CloudFormation stack e creare risorse Lambda, API Gateway, Amazon Cognito e Amazon S3 CloudFront.

  • Account Amazon Quick Sight: un account Quick Sight attivo con almeno una dashboard contenente immagini. Per istruzioni di configurazione, consulta Tutorial: Creazione di un pannello di controllo Amazon Quick Sight utilizzando dati di esempio nella documentazione di Amazon Quick Suite.

  • Un ambiente di sviluppo composto da:

    • Node.js (versione 16 o successiva)

    • npm o yarn installato

    • Vite come strumento di compilazione di React

    • React (versione 19.1.1)

  • Condivisione della dashboard: le dashboard devono essere condivise in Quick Sight e l'implementatore deve effettuare il login per accedere alle immagini o ai dashboard incorporati.

Limitazioni

  • Questo modello utilizza il metodo di incorporamento degli utenti registrati, che richiede agli implementatori di disporre di un account Quick Sight attivo.

  • L'accesso è limitato ai dashboard e agli elementi visivi che vengono condivisi esplicitamente con l'utente Quick Sight autenticato che implementa questo modello. Se l'implementatore non dispone dei diritti di accesso corretti, la generazione dell'URL di incorporamento avrà esito negativo e gli elementi visivi non verranno caricati.

  • Lo CloudFormation stack deve essere distribuito in un ambiente in Regione AWS cui siano supportati Quick Sight, API Gateway e Amazon Cognito. Per la disponibilità per regione, consulta Servizi AWS per regione.

Versioni del prodotto

Architecture

Architettura Target

Il diagramma seguente mostra l'architettura e il flusso di lavoro per questo modello.

Architettura e flusso di lavoro per incorporare immagini Quick Sight in un'applicazione React.

In questo flusso di lavoro:

  1. L'utente accede all'applicazione. L'utente apre l'applicazione web React utilizzando un browser. La richiesta viene indirizzata a una CloudFront distribuzione, che funge da rete di distribuzione dei contenuti per l'applicazione.

  2. AWS WAF filtra le richieste dannose. Prima che la richiesta arrivi CloudFront, passa AWS WAF. AWS WAF ispeziona il traffico e blocca eventuali richieste dannose o sospette in base alle regole di sicurezza.

  3. Amazon S3 serve file statici. Se la richiesta è pulita, CloudFront recupera le risorse statiche del frontend (HTML, JS, CSS) da un bucket S3 privato utilizzando Origin Access Control (OAC) e le invia al browser.

  4. L'utente accede. Dopo il caricamento dell'applicazione, l'utente accede tramite Amazon Cognito, che autentica l'utente e restituisce un token web JSON (JWT) sicuro per l'accesso all'API autorizzato.

  5. L'applicazione effettua una richiesta API. Dopo il login, l'applicazione React effettua una chiamata sicura all'/get-embed-urlendpoint su API Gateway e passa il token JWT nell'intestazione della richiesta per l'autenticazione.

  6. Il token è convalidato. API Gateway convalida il token utilizzando un autorizzatore Amazon Cognito. Se il token è valido, la richiesta procede; in caso contrario, viene rifiutata con una risposta 401 (non autorizzata).

  7. La richiesta viene indirizzata a Lambda per l'elaborazione. La richiesta convalidata viene quindi inoltrata a una funzione Lambda di backend. Questa funzione è responsabile della generazione dell'URL di incorporamento per l'immagine Quick Sight richiesta.

  8. Lambda genera l'URL di incorporamento da Quick Sight. IAM utilizza un ruolo IAM con le autorizzazioni appropriate per chiamare l'GenerateEmbedUrlForRegisteredUserAPI Quick Sight e generare un URL visivo sicuro e con ambito utente.

  9. Lambda restituisce l'URL di incorporamento ad API Gateway. Lambda invia l'URL di incorporamento generato ad API Gateway come parte di una risposta JSON. Questa risposta viene quindi preparata per essere inviata al frontend.

  10. L'URL di incorporamento viene inviato al browser. L'URL di incorporamento viene restituito al browser come risposta API.

  11. L'immagine viene mostrata all'utente. L'applicazione React riceve la risposta e utilizza l'SDK Quick Sight Embedding per rendere l'immagine specifica all'utente.

Automazione e scalabilità

Le implementazioni di backend e frontend sono completamente automatizzate utilizzando CloudFormation, che fornisce tutte le AWS risorse richieste, tra cui Amazon Cognito, Lambda, API Gateway, Amazon S3,, ruoli IAM e Amazon in un' AWS WAF unica implementazione. CloudFront CloudWatch

Questa automazione garantisce un'infrastruttura coerente e ripetibile in tutti gli ambienti. Tutti i componenti si scalano automaticamente: Lambda si adatta alle chiamate di funzione, CloudFront fornisce i contenuti memorizzati nella cache a livello globale e API Gateway si adatta alle richieste in arrivo.

Tools (Strumenti)

Servizi AWS

  • Amazon Quick Sight è un servizio di business intelligence nativo per il cloud che ti aiuta a creare, gestire e incorporare dashboard e immagini interattive.

  • I gestori di Amazon API Gateway APIs fungono da ponte tra l'applicazione React e i servizi di backend.

  • AWS Lambdaè un servizio di elaborazione serverless che questo modello utilizza per generare un incorporamento sicuro di Quick Sight in URLs modo dinamico e scalabile automaticamente in base alle richieste.

  • Amazon Cognito fornisce l'autenticazione e l'autorizzazione per gli utenti ed emette token sicuri per l'accesso alle API.

  • Amazon S3 ospita risorse frontend statiche per questo modello e le fornisce in modo sicuro. CloudFront

  • Amazon CloudFront distribuisce contenuti frontend a livello globale con bassa latenza e si integra con AWS WAF il filtraggio del traffico.

  • AWS WAFprotegge l'applicazione Web dal traffico dannoso applicando regole di sicurezza e limitando la velocità.

  • AWS CloudFormationautomatizza il provisioning e la configurazione di tutte le risorse delle applicazioni in un'unica implementazione.

  • Amazon CloudWatch raccoglie log e parametri da Lambda, API Gateway e per il monitoraggio AWS WAF e la risoluzione dei problemi.

Strumenti di sviluppo

  • React JS è un framework di frontend che questo modello utilizza per creare l'applicazione web e integrare elementi visivi Quick Sight incorporati.

  • Vite è uno strumento di compilazione utilizzato per lo sviluppo rapido e le build di produzione ottimizzate dell'applicazione React.

  • Quick Sight Embedding SDK facilita l'incorporamento di elementi visivi Quick Sight nell'applicazione React e consente un'interazione perfetta tra l'applicazione e le immagini.

Archivio di codice

Il codice per questo pattern è disponibile nel repository GitHub Amazon Quick Sight Visual Embedding in React.

Best practice

Questo modello implementa automaticamente le seguenti best practice di sicurezza:

  • Utilizza i pool di utenti di Amazon Cognito per l'autenticazione basata su JWT, con autenticazione a più fattori (MFA) opzionale.

  • Protegge APIs con gli autorizzatori di Amazon Cognito e applica le politiche IAM con privilegi minimi su tutti i servizi.

  • Implementa l'incorporamento degli utenti registrati Quick Sight e assegna automaticamente agli utenti il ruolo di lettore.

  • Applica la crittografia in transito che supporta TLS 1.2 e versioni successive tramite HTTPS. CloudFront

  • Crittografa i dati inattivi utilizzando AES-256 per Amazon S3 con controllo delle versioni e OAC.

  • Configura i piani di utilizzo di API Gateway con throttling e quote.

  • Protegge Lambda con concorrenza riservata e protezione delle variabili d'ambiente.

  • Abilita la registrazione per Amazon S3 CloudFront, Lambda e API Gateway; monitora i servizi utilizzando. CloudWatch

  • Crittografa i log, applica i controlli di accesso e applica politiche di negazione per i caricamenti non HTTPS o non crittografati.

Inoltre, consigliamo quanto segue:

  • Utilizzalo CloudFormation per automatizzare le implementazioni e mantenere configurazioni coerenti tra gli ambienti.

  • Assicurati che ogni utente disponga delle autorizzazioni Quick Sight corrette per accedere alle immagini incorporate.

  • Proteggi gli endpoint API Gateway con gli autorizzatori di Amazon Cognito e applica il principio del privilegio minimo per tutti i ruoli IAM.

  • Archivia informazioni sensibili come Amazon Resource Names (ARNs) e IDs in variabili di ambiente anziché codificarle.

  • Ottimizza le funzioni Lambda riducendo le dipendenze e migliorando le prestazioni di avviamento a freddo. Per ulteriori informazioni, consulta il post AWS sul blog Ottimizzazione delle prestazioni di avviamento a freddo dell' AWS Lambda utilizzo di strategie di innesco avanzate con. SnapStart

  • Aggiungi il tuo CloudFront dominio all'elenco delle autorizzazioni di Quick Sight per abilitare l'incorporamento visivo sicuro.

  • Monitora le prestazioni e la sicurezza utilizzando CloudWatch e AWS WAF per la registrazione, gli avvisi e la protezione del traffico.

Altre best practice consigliate

  • Utilizza domini personalizzati con certificati SSL AWS Certificate Manager per fornire un'esperienza utente sicura e personalizzata.

  • Crittografa i dati CloudWatch e i log di Amazon S3 utilizzando chiavi AWS Key Management Service gestite dal cliente AWS KMS() per un maggiore controllo sulla crittografia.

  • Estendi AWS WAF le regole con geo-blocking, SQL injection (SQLi), protezione Cross-Site Scripting (XSS) e filtri personalizzati per una maggiore prevenzione delle minacce.

  • Attivate gli CloudWatch allarmi e garantite il monitoraggio AWS Config, il controllo e AWS CloudTrail la conformità della configurazione in tempo reale.

  • Applica politiche IAM granulari, applica la rotazione delle chiavi API e consenti l'accesso tra account solo quando assolutamente necessario.

  • Esegui valutazioni di sicurezza regolari per garantire l'allineamento con i framework di conformità come System and Organization Controls 2 (SOC 2), il Regolamento generale sulla protezione dei dati (GDPR) e l'Health Insurance Portability and Accountability Act (HIPAA).

Epiche

OperazioneDescriptionCompetenze richieste

Clonare il repository.

Clona il GitHub repository di questa soluzione sul tuo sistema locale e vai alla directory del progetto:

git clone https://github.com/aws-samples/sample-quicksight-visual-embedding.git cd sample-quicksight-visual-embedding

Questo repository contiene il CloudFormation modello e il codice sorgente React necessari per distribuire la soluzione.

Sviluppatore di app
OperazioneDescriptionCompetenze richieste

Implementa il modello.

  1. Accedi a Console di gestione AWS e apri la AWS CloudFormation console.

  2. Nella pagina Pile, scegli Crea pila in alto a destra, quindi scegli Con nuove risorse (standard).

  3. Nella pagina Crea stack, per Prerequisito — Prepara modello, scegli Scegli un modello esistente.

  4. In Specify template (Specifica il modello), scegliere Upload a template file (Carica un file modello).

  5. Carica il template.yaml file dal tuo GitHub repository locale, quindi scegli Avanti.

  6. Nella pagina Specificare i dettagli dello stack, inserisci il nome dello stack (ad esempio,). quicksight-embedding-stack

  7. Nella pagina Configura le opzioni dello stack, mantieni le impostazioni predefinite e seleziona la casella per confermare la creazione di risorse IAM. Scegli Next (Successivo).

  8. Nella pagina Rivedi e crea, scegli Invia.

 Per ulteriori informazioni, consulta Creazione e gestione degli stack nella CloudFormation documentazione.

Amministratore AWS

Monitora la creazione di stack.

Monitora lo stack nella scheda Eventi fino a quando il suo stato non è CREATE_COMPLETE.

Amministratore AWS

Recupera gli output dello stack.

  1. Quando la distribuzione è completa, scegli la scheda Output.

  2. Nota gli output principali:ApiGatewayUrl,, UserPoolId UserPoolClientIdCloudFrontDomainName, e. S3BucketName Utilizzerai queste informazioni nei passaggi successivi.

Amministratore AWS
OperazioneDescriptionCompetenze richieste

Recupera gli identificatori visivi Quick Sight.

  1. Apri la dashboard di Quick Sight.

  2. Annota l'ID della dashboard, l'ID del foglio e l'ID visivo di ogni elemento visivo che intendi incorporare nella tua applicazione web.

Amministratore Quick Sight

Configura il tuo ambiente React locale.

Per configurare il tuo ambiente React locale e collegarlo alle AWS risorse, crea un .env file nella my-app/ cartella del tuo GitHub repository locale. Compila il file con:

  • Il tuo Regione AWS

  • Informazioni sul pool di Amazon Cognito (dagli CloudFormation stack output)

  • Endpoint API Gateway (dagli output CloudFormation dello stack)

  • Visualizzazione rapida (,, IDs ) DashboardId SheetId VisualId

Ecco un .env file di esempio:

VITE_AWS_REGION=us-east-1 # Cognito Configuration (from CloudFormation outputs) VITE_USER_POOL_ID=us-east-1_xxxxxxxxx VITE_USER_POOL_WEB_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx # API Configuration (from CloudFormation outputs) VITE_API_URL=https:/your-api-id.execute-api.us-east-1.amazonaws.com/prod # QuickSight Visual Configuration VITE_DASHBOARD_ID=your-dashboard-id VITE_SHEET_ID=your-sheet-id VITE_VISUAL_ID=your-visual-id
Sviluppatore di app
OperazioneDescriptionCompetenze richieste

Creare o gestire utenti in Cognito

Per consentire l'accesso degli utenti autenticati agli elementi visivi Quick Sight incorporati, devi prima creare utenti in Amazon Cognito:

  1. Sulla console Amazon Cognito, scegli Pool di utenti, quindi scegli il pool corrispondente UserPoolId (dagli CloudFormation output).

  2. Aggiungi utenti al pool. Puoi scegliere tra due opzioni:

Amministratore AWS

Fornisci l'accesso Quick Sight alla dashboard

Per consentire l'accesso agli elementi visivi di Quick Sight, concedi l'autorizzazione Viewer agli utenti autenticati:

  1. Nella console Quick Sight, scegli Dashboard.

  2. Seleziona la dashboard che desideri condividere scegliendone il nome.

  3. Nell'angolo in alto a destra della pagina del pannello di controllo, scegli Condividi.

  4. Nel pannello di condivisione, scegli Condividi con utenti specifici.

  5. Per aggiungere nuovi utenti, scegli Invita utenti o l'icona più (+).

  6. Nel campo e-mail, inserisci l'indirizzo email completo del destinatario. (Questa e-mail deve corrispondere esattamente al login di Amazon Cognito dell'utente)

  7. Dal menu Autorizzazione accanto al campo e-mail, scegli Viewer.

  8. Per inviare l'invito e concedere l'accesso, scegli Condividi.

Ogni utente riceverà un'email con un link alla dashboard. Puoi modificare le autorizzazioni in qualsiasi momento tramite il menu Condividi.

Per ulteriori informazioni, consulta Concessione dell'accesso a singoli utenti e gruppi Amazon Quick Sight a una dashboard in Amazon Quick Sight nella documentazione di Amazon Quick Suite.

Amministratore Quick Sight
OperazioneDescriptionCompetenze richieste

Installa le dipendenze e crea il progetto.

Nella directory dell'applicazione React, esegui i seguenti comandi per generare file di produzione ottimizzati:

cd my-app npm install npm run build
Sviluppatore di app

Carica i file di build su Amazon S3.

Carica tutti i file dalla my-app/dist/ directory nel bucket S3 fornito da CloudFormation (non caricare la cartella stessa).

Sviluppatore di app

Crea un'invalidazione. CloudFront

Sulla CloudFront console, crea un'invalidazione per il percorso di aggiornamento dei contenuti memorizzati nella cache /* dopo la distribuzione. Per istruzioni, consulta Invalidare i file nella documentazione. CloudFront

Amministratore AWS
OperazioneDescriptionCompetenze richieste

Aggiungi il CloudFront dominio all'elenco delle autorizzazioni di Quick Sight.

Per consentire al tuo CloudFront dominio di incorporare in modo sicuro gli elementi visivi Quick Sight:

  1. Sulla console Quick Sight, scegli Gestisci Quick Sight, Domains and Embedding.

  2. Aggiungi il CloudFront dominio alla casella Dominio (ad esempio,https://d1234567890abc.cloudfront.net).

  3. Scegli Add domain (Aggiungi dominio).

Amministratore Quick Sight
OperazioneDescriptionCompetenze richieste

Apri l'applicazione React.

Usa il CloudFront dominio (dagli CloudFormation output) per aprire l'applicazione web React distribuita in un browser.

Proprietario dell'app

Verifica l'autenticazione.

Accedi all'applicazione utilizzando le credenziali di Amazon Cognito per verificare il flusso di autenticazione e la convalida JWT tramite API Gateway.

Proprietario dell'app

Verifica gli elementi visivi incorporati.

Verifica che le immagini Quick Sight vengano caricate correttamente all'interno dell'applicazione in base alle autorizzazioni di accesso specifiche dell'utente.

Proprietario dell'app

Convalida la connettività API e Lambda.

Verifica che l'applicazione sia in grado di chiamare correttamente l'/get-embed-urlAPI e recuperare un URLs incorporamento Quick Sight valido senza errori.

Proprietario dell'app
OperazioneDescriptionCompetenze richieste

Monitora utilizzando CloudWatch.

È possibile utilizzare strumenti AWS di osservabilità per monitorare l'applicazione e mantenere prestazioni sicure e scalabili in produzione.

Controlla i log Lambda, le metriche di API Gateway e gli eventi di autenticazione di Amazon Cognito CloudWatch per garantire lo stato delle applicazioni e rilevare anomalie.

Amministratore AWS

Monitora AWS WAF e CloudFront registra.

Controlla AWS WAF i log per verificare la presenza di richieste bloccate o sospette e i log di CloudFront accesso per verificare le prestazioni e le metriche di memorizzazione nella cache.

Amministratore AWS

risoluzione dei problemi

ProblemaSoluzione

Errore «Dominio non consentito»

  1. Nella console Quick Sight, scegli Gestisci Quick Sight, Domains and Embedding.

  2. Aggiungi il tuo CloudFront dominio (ad esempio,https://d1234567890abc.cloudfront.net).

  3. Salva la configurazione e ricarica l'applicazione.

Errori di autenticazione

Possibili cause:

  • ID del pool di utenti Amazon Cognito o ID client dell'applicazione errato nel .env file.

  • L'utente non è stato confermato nel pool di utenti di Amazon Cognito.

  • Token JWT non valido o mancante nelle richieste API.

Soluzioni:

  • Verifica i valori di configurazione di Amazon Cognito nel .env file.

  • Sulla console Amazon Cognito, controlla la scheda Utenti per verificare che l'utente sia attivo.

  • Verifica che l'intestazione di autorizzazione contenga un token JWT valido.

  • Sulla console API Gateway, seleziona Authorizers per verificare che API Gateway utilizzi l'autorizzatore Amazon Cognito per l'autenticazione.

Errori dell'API Gateway

Possibili cause:

  • Autorizzatore Amazon Cognito mancante o configurato in modo errato in API Gateway.

  • Autorizzazioni Lambda insufficienti per chiamare l'API Quick Sight.

  • Mancata corrispondenza dell'URL dell'API tra e output.env. CloudFormation

Soluzioni:

  • Riconferma che l'URL di richiamo dell'API Gateway sia presente nel file.env.

  • Sulla console API Gateway, seleziona Authorizers per verificare la configurazione di Amazon Cognito.

  • Allega la policy IAM richiesta con quicksight:GenerateEmbedUrlForRegisteredUser al ruolo di esecuzione Lambda.

  • CloudWatch Esamina i log per verificare eventuali errori dettagliati relativi all'API o alle autorizzazioni. Per ulteriori informazioni, consulta la documentazione di API Gateway.

Le immagini di Quick Sight non si caricano

Possibili cause:

  • ID dashboard Quick Sight, ID del foglio o ID visivo non corretti nella configurazione dell'ambiente.

  • Nessun accesso da parte dell'utente Quick Sight alla visualizzazione o alla dashboard.

  • Configurazione CORS (Cross-Origin Resource Sharing) mancante in API Gateway.

Soluzioni:

  • Conferma Quick Sight IDs dal menu a tre punti nell'angolo in alto a destra della visuale del dashboard.

  • Verifica che l'utente Quick Sight abbia il ruolo di visualizzatore per la dashboard condivisa.

  • Abilita CORS in API Gateway e ridistribuisci l'API. Per ulteriori informazioni, consulta la documentazione di API Gateway.

  • Controllate la presenza di CORS nella console del browser per individuare eventuali errori relativi alla rete.

Errore «L'utente non ha accesso»

Possibili cause:

  • L'e-mail dell'utente non è stata condivisa con la dashboard di Quick Sight.

  • Ruolo o autorizzazione utente errati in Quick Sight.

Soluzione::

  1. Sulla console Quick Sight, apri la dashboard, quindi scegli Condividi, Condividi dashboard.

  2. Aggiungi l'indirizzo e-mail dell'utente (corrispondente all'e-mail di accesso ad Amazon Cognito).

  3. Assegna il ruolo di autorizzazione Viewer.

  4. Chiedi all'utente di disconnettersi e accedere nuovamente per aggiornare le autorizzazioni.

Risorse correlate

AWS documentazione

Tutorial e video