Fase 2: Ottenimento dell'URL con il codice di autenticazione allegato

Importante

Amazon QuickSight dispone di nuove operazioni API per l'incorporamento dell'analisi: GenerateEmbedUrlForAnonymousUser e GenerateEmbedUrlForRegisteredUser.

Puoi comunque utilizzare le operazioni API GetDashboardEmbedUrl e GetSessionEmbedUrl per incorporare i pannelli di controllo e la console QuickSight, ma questi non conterranno le funzionalità di incorporamento più recenti. Per l'esperienza di incorporamento più recente e aggiornata, consulta Incorporamento dell'analisi QuickSight nelle applicazioni

Nella sezione seguente, è possibile scoprire come autenticare l'utente e ottenere l'URL della sessione della console incorporabile nel server delle applicazioni.

Quando un utente accede all'applicazione, l'applicazione assume il ruolo IAM per conto dell'utente. Quindi aggiunge l'utente a QuickSight, se tale utente non esiste già. In seguito, sarà necessario passare un identificatore come l'ID della sessione del ruolo univoco.

L'esecuzione della procedura descritta garantisce che per ogni visualizzatore della sessione della console viene effettuato il provisioning in modo univoco in QuickSight. Applica inoltre le impostazioni per utente, ad esempio la sicurezza a livello di riga e le impostazioni predefinite dinamiche per i parametri.

Gli esempi seguenti eseguono l'autenticazione IAM per conto dell'utente. Questo codice viene eseguito sul server delle applicazioni.

Java


import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.BasicAWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.quicksight.AmazonQuickSight;
import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder;
import com.amazonaws.services.quicksight.model.GetSessionEmbedUrlRequest;
import com.amazonaws.services.quicksight.model.GetSessionEmbedUrlResult;

/**
 * Class to call QuickSight AWS SDK to get url for session embedding.
 */
public class GetSessionEmbedUrlQSAuth {

    private final AmazonQuickSight quickSightClient;

    public GetSessionEmbedUrlQSAuth() {
        this.quickSightClient = AmazonQuickSightClientBuilder
                .standard()
                .withRegion(Regions.US_EAST_1.getName())
                .withCredentials(new AWSCredentialsProvider() {
                                     @Override
                                     public AWSCredentials getCredentials() {
                                         // provide actual IAM access key and secret key here
                                         return new BasicAWSCredentials("access-key", "secret-key");
                                     }

                                     @Override
                                     public void refresh() {}
                                 }
                )
                .build();
    }

    public String getQuicksightEmbedUrl(
            final String accountId, // YOUR AWS ACCOUNT ID
            final String userArn // REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
    ) throws Exception {
        GetSessionEmbedUrlRequest getSessionEmbedUrlRequest = new GetSessionEmbedUrlRequest()
                .withAwsAccountId(accountId)
                .withEntryPoint("/start")
                .withUserArn(userArn);

        GetSessionEmbedUrlResult sessionEmbedUrl = quickSightClient.getSessionEmbedUrl(getSessionEmbedUrlRequest);

        return sessionEmbedUrl.getEmbedUrl();
    }
}

JavaScript


global.fetch = require('node-fetch');
const AWS = require('aws-sdk');

function getSessionEmbedURL(
    accountId, // YOUR AWS ACCOUNT ID
    userArn, // REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
    getEmbedUrlCallback, // GETEMBEDURL SUCCESS CALLBACK METHOD
    errorCallback // GETEMBEDURL ERROR CALLBACK METHOD
    ) {
    const getSessionParams = {
        AwsAccountId: accountId,
        EntryPoint: "/start",
        UserArn: userArn,
        SessionLifetimeInMinutes: 600,
    };

    const quicksightGetSession = new AWS.QuickSight({
        region: process.env.AWS_REGION,
    });

    quicksightGetSession.getSessionEmbedUrl(getSessionParams, function(err, data) {
        if (err) {
            console.log(err, err.stack);
            errorCallback(err);
        } else {
            const result = {
                "statusCode": 200,
                "headers": {
                    "Access-Control-Allow-Origin": "*", // USE YOUR WEBSITE DOMAIN TO SECURE ACCESS TO GETEMBEDURL API
                    "Access-Control-Allow-Headers": "Content-Type"
                },
                "body": JSON.stringify(data),
                "isBase64Encoded": false
            }
            getEmbedUrlCallback(result);
        }
    });
}

Python3


import json
import boto3
from botocore.exceptions import ClientError
import time

# Create QuickSight and STS clients
qs = boto3.client('quicksight',region_name='us-east-1')
sts = boto3.client('sts')

# Function to generate embedded URL
# accountId: YOUR AWS ACCOUNT ID
# userArn: REGISTERED USER ARN TO USE FOR EMBEDDING. REFER TO GETEMBEDURL SECTION IN DEV PORTAL TO FIND OUT HOW TO GET USER ARN FOR A QUICKSIGHT USER
def getSessionEmbedURL(accountId, userArn):
    try:
        response = qs.get_session_embed_url(
            AwsAccountId = accountId,
            EntryPoint = "/start",
            UserArn = userArn,
            SessionLifetimeInMinutes = 600
        )
            
        return {
            'statusCode': 200,
            'headers': {"Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "Content-Type"},
            'body': json.dumps(response),
            'isBase64Encoded':  bool('false')
        }
    except ClientError as e:
        print(e)
        return "Error generating embeddedURL: " + str(e)

Node.js

L'esempio seguente mostra il codice JavaScript (Node.js) che è possibile utilizzare nel server delle applicazioni per ottenere l'URL della sessione della console incorporata. È possibile utilizzare questo URL nel sito Web o nell'applicazione per visualizzare la sessione della console.


const AWS = require('aws-sdk');
            const https = require('https');
            
            var quicksight = new AWS.Service({
                apiConfig: require('./quicksight-2018-04-01.min.json'),
                region: 'us-east-1',
            });
            
            quicksight.GetSessionEmbedUrl({
                'AwsAccountId': '111122223333',
                'EntryPoint': 'https://url-for-console-page-to-open',
                'SessionLifetimeInMinutes': 600,
                'UserArn': 'USER_ARN'
            
            }, function(err, data) {
                console.log('Errors: ');
                console.log(err);
                console.log('Response: ');
                console.log(data);
            });


//The URL returned is over 900 characters. For this example, we've shortened the string for
            //readability and added ellipsis to indicate that it's incomplete.
                                { Status: 200,
              EmbedUrl: 'https://dashboards.example.com/embed/620bef10822743fab329fb3751187d2d…
              RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' }

.NET/C#

L'esempio seguente mostra il codice .NET/C# che è possibile utilizzare nel server delle applicazioni per ottenere l'URL per la sessione della console incorporata. È possibile utilizzare questo URL nel sito Web o nell'applicazione per visualizzare la console.



            var client = new AmazonQuickSightClient(
                AccessKey,
                SecretAccessKey,
                sessionToken,
                Amazon.RegionEndpoint.USEast1);
            try
            {
                Console.WriteLine(
                    client.GetSessionEmbedUrlAsync(new GetSessionEmbedUrlRequest
                    {
                'AwsAccountId': '111122223333',
                'EntryPoint': 'https://url-for-console-page-to-open',
                'SessionLifetimeInMinutes': 600,
                'UserArn': 'USER_ARN'
                        AwsAccountId = 111122223333,
                        EntryPoint = https://url-for-console-page-to-open,
                        SessionLifetimeInMinutes = 600,
                        UserArn = 'USER_ARN'
                    }).Result.EmbedUrl
                );
            } catch (Exception ex) {
                Console.WriteLine(ex.Message);
            }

AWS CLI

Per assumere quel ruolo, scegli una delle seguenti operazioni API di AWS Security Token Service (AWS STS):

AssumeRole: utilizza questa operazione quando usi un'identità IAM per assumere il ruolo.
AssumeRoleWithWebIdentity: utilizza questa operazione quando usi un gestore delle identità Web per autenticare l'utente.
AssumeRoleWithSaml: utilizza questa operazione quando usi SAML per autenticare gli utenti.

L'esempio seguente mostra il comando dell'interfaccia a riga di comando per impostare il ruolo IAM. Il ruolo deve avere le autorizzazioni abilitate per quicksight:GetSessionEmbedUrl. Se stai adottando un approccio just-in-time per aggiungere utenti quando aprono QuickSight per la prima volta, per il ruolo è necessario abilitare anche le autorizzazioni per quicksight:RegisterUser.


aws sts assume-role \
     --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --role-session-name john.doe@example.com

L'operazione assume-role restituisce tre parametri di output: la chiave di accesso, la chiave segreta e il token della sessione.

Nota

Se si verifica un errore ExpiredToken durante la chiamata all'operazione AssumeRole, vuol dire che il SESSION TOKEN precedente è ancora presente nelle variabili di ambiente. Cancellala impostando le seguenti variabili:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

L'esempio seguente mostra come impostare questi tre parametri nell'interfaccia a riga di comando. Se usi un computer Microsoft Windows, utilizza set invece di export.


export AWS_ACCESS_KEY_ID     = "access_key_from_assume_role"
export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role"
export AWS_SESSION_TOKEN     = "session_token_from_assume_role"

L'esecuzione di questi comandi imposta l'ID della sessione del ruolo dell'utente che visita la pagina del tuo sito Web suembedding_quicksight_console_session_role/john.doe@example.com. L'ID della sessione del ruolo è costituito dal nome del ruolo di role-arn e dal valore role-session-name. L'utilizzo dell'ID della sessione del ruolo univoco per ciascun utente garantisce che le autorizzazioni appropriate siano impostate per ogni utente. Impedisce inoltre il throttling dell'accesso degli utenti. La limitazione (della larghezza di banda della rete) è una funzionalità di sicurezza che impedisce allo stesso utente di accedere a QuickSight da più posizioni.

Inoltre, l'ID della sessione del ruolo diventa il nome utente in QuickSight. È possibile usare questo modello per effettuare il provisioning degli utenti in QuickSight in anticipo o per effettuare il provisioning la prima volta che accedono a una sessione della console.

L'esempio seguente mostra il comando dell'interfaccia a riga di comando che è possibile utilizzare per effettuare il provisioning di un utente. Per ulteriori informazioni su RegisterUser, DescribeUser e altre operazioni API QuickSight, consulta la Documentazione di riferimento delle API QuickSight.


aws quicksight register-user \
     --aws-account-id 111122223333 \
     --namespace default \
     --identity-type IAM \
     --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
     --user-role READER \
     --user-name jhnd \
     --session-name "john.doe@example.com" \
     --email john.doe@example.com \
     --region us-east-1 \
     --custom-permissions-name TeamA1

Se l'utente viene autenticato tramite Microsoft AD, non è necessario utilizzare RegisterUser per configurarlo. In caso contrario, deve essere automaticamente sottoscritto al primo accesso a QuickSight. Per gli utenti Microsoft AD, puoi utilizzare DescribeUser per ottenere l'ARN dell'utente.

La prima volta che un utente accede a QuickSight, è anche possibile aggiungerlo al gruppo appropriato. L'esempio seguente mostra il comando dell'interfaccia a riga di comando per aggiungere un utente a un gruppo.


aws quicksight create-group-membership \
     --aws-account-id=111122223333 \
     --namespace=default \
     --group-name=financeusers \
     --member-name="embedding_quicksight_dashboard_role/john.doe@example.com"

Hai ora un utente dell'applicazione che è anche un utente di QuickSight e che ha accesso alla sessione della console QuickSight.

Infine, per ottenere un URL firmato per la sessione della console, chiama get-session-embed-url dal server delle applicazioni. Ciò restituisce l'URL della sessione della console incorporabile. L'esempio seguente mostra come ottenere l'URL per una sessione della console incorporata utilizzando una chiamata sul lato server per gli utenti autenticati tramite AWS Managed Microsoft AD o single sign-on (Centro identità IAM).


aws quicksight get-dashboard-embed-url \
     --aws-account-id 111122223333 \
     --entry-point the-url-for--the-console-session \
     --session-lifetime-in-minutes 600 \
     --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession

Per ulteriori informazioni sull'utilizzo di questa operazione, consulta GetSessionEmbedUrl. Puoi utilizzare questa API e altre operazioni nel tuo codice.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Fase 1: Configurazione delle autorizzazioni

Fase 3: Incorporamento dell'URL