Schritt 2: Abrufen der URL mit dem angehängten Authentifizierungscode

Wichtig

Amazon QuickSight verfügt über neue APIs zum Einbetten von Analysen: GenerateEmbedUrlForAnonymousUser und GenerateEmbedUrlForRegisteredUser.

Sie können weiterhin die GetDashboardEmbedUrl- und GetSessionEmbedUrl-APIs verwenden, um Dashboards und die QuickSight-Konsole einzubetten, sie enthalten jedoch nicht die neuesten Einbettungsfunktionen. Aktuelle Informationen zum Einbetten finden Sie unter Einbetten von QuickSight-Analytik in Ihre Anwendungen.

Im folgenden Abschnitt erfahren Sie, wie Sie Ihren Benutzer authentifizieren und die einbettungsfähige Konsolensitzung-URL auf Ihrem Anwendungsserver abrufen.

Wenn ein Benutzer auf Ihre App zugreift, übernimmt die App die IAM-Rolle für den Benutzer. Anschließend fügt sie den Benutzer zu QuickSight hinzu, wenn dieser Benutzer nicht bereits vorhanden ist. Anschließend übergibt sie eine ID als eindeutige Rollensitzungs-ID.

Durch die Ausführung der beschriebenen Schritte wird sichergestellt, dass jeder Viewer der Konsolensitzung in QuickSight eindeutig bereitgestellt wird. Dazu werden benutzerspezifische Einstellungen erzwungen, etwa Sicherheit auf niedriger Ebene sowie dynamische Standardwerte für Parameter.

In den folgenden Beispielen wird die IAM-Authentifizierung im Namen des Benutzers durchgeführt. Dieser Code wird auf Ihrem App-Server ausgeführt.

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

Das folgende Beispiel zeigt das JavaScript (Node.js), das Sie auf dem App-Server verwenden können, um die URL für die eingebettete Konsolensitzung abzurufen. Sie können diese URL auf Ihrer Website oder in Ihrer App verwenden, um die Konsolensitzung aufzurufen.


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#

Das folgende Beispiel zeigt den .NET/C # Code, den Sie auf dem App-Server verwenden können, um die URL für die eingebettete Konsolensitzung abzurufen. Sie können diese URL auf Ihrer Website oder in Ihrer App verwenden, um die Konsole aufzurufen.



            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

Wählen Sie zum Übernehmen der Rolle eine der folgenden AWS Security Token Service (AWS STS)-API-Operationen:

AssumeRole – Verwenden Sie diese Operation, wenn eine IAM-Identität zum Übernehmen der Rolle verwendet wird.
AssumeRoleWithWebIdentity – Verwenden Sie diese Operation, wenn Sie einen Web-Identitätsanbieter zum Authentifizieren Ihres Benutzers verwenden.
AssumeRoleWithSaml – Verwenden Sie diese Operation, wenn Sie SAML zum Authentifizieren Ihrer Benutzer verwenden.

Das folgende Beispiel zeigt den CLI-Befehl zum Festlegen der IAM-Rolle. Für die Rolle müssen die Berechtigungen für quicksight:GetSessionEmbedUrl aktiviert sein. Wenn Sie einen Just-in-Time-Ansatz verfolgen, um Benutzer hinzuzufügen, wenn sie QuickSight zum ersten Mal öffnen, müssen für die Rolle auch die entsprechenden Berechtigungen für quicksight:RegisterUser aktiviert sein.


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

Die assume-role-Operation gibt drei Parameter zurück: den Zugriffsschlüssel, den geheimen Schlüssel und das Sitzungs-Token.

Anmerkung

Wenn beim Aufrufen der Operation AssumeRole der Fehler ExpiredToken gemeldet wird, liegt dies wahrscheinlich daran, dass sich der vorherige SESSION TOKEN-Wert noch in den Umgebungsvariablen befindet. Deaktivieren Sie dies, indem Sie die folgenden Variablen einstellen:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN

Das folgende Beispiel zeigt, wie Sie diese drei Parameter in der CLI einrichten. Wenn Sie einen Microsoft Windows-Computer nutzen, verwenden Sie set anstelle von 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"

Diese Befehle setzen die Rollensitzungs-ID des Benutzers, der Ihre Website besucht, auf embedding_quicksight_console_session_role/john.doe@example.com. Die Rollensitzungs-ID besteht aus dem Rollennamen role-arn und dem role-session-name-Wert. Die Verwendung der eindeutigen Rollensitzungs-ID für jeden Benutzer garantiert, dass fpr jeden benutzer die korrekten Berechtigungen eingerichtet werden. Außerdem wird eine Drosselung des Benutzerzugriffs verhindert. Die Drosselung ist ein Sicherheitsfeature, das verhindert, dass ein Benutzer von mehreren Standorten aus auf QuickSight zugreift.

Die Rollensitzungs-ID wird außerdem zum Benutzernamen in QuickSight. Sie können mit diesem Muster Ihre Benutzer in QuickSight im Voraus oder dann, wenn Sie auf eine Konsolensitzung zugreifen, bereitstellen.

Das folgende Beispiel zeigt den CLI-Befehl, den Sie verwenden können, um einen Benutzer bereitstellen. Weitere Informationen zu RegisterUser, DescribeUser und anderen QuickSight-API-Operationen finden Sie in der QuickSight-API-Referenz.


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

Wenn der Benutzer durch Microsoft AD authentifiziert wird, müssen Sie RegisterUser nicht verwenden, um sie einzurichten. Stattdessen sollten sie beim ersten Zugriff auf QuickSight automatisch angemeldet werden. Für Microsoft AD-Benutzer können Sie DescribeUser verwenden, um den Benutzer ARN zu erhalten.

Wenn ein Benutzer zum ersten Mal auf QuickSight zugreift, können Sie diesen Benutzer auch der entsprechenden Gruppe hinzufügen. Das folgende Beispiel zeigt den CLI-Befehl zum Hinzufügen eines Benutzers zu einer Gruppe.


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

Sie haben jetzt einen Benutzer Ihrer App, der auch Benutzer von QuickSight ist und auf die QuickSight-Konsolensitzung zugreifen kann.

Um eine signierte URL für die Konsolensitzung zu erhalten, rufen Sie schließlich get-session-embed-url vom App-Server auf. Dadurch wird die URL der einbettbaren Konsolensitzung zurückgegeben. Das folgende Beispiel zeigt, wie die URL für eine eingebettete Konsolensitzung mithilfe eines serverseitigen Aufrufs für Benutzer abgerufen wird, die über Single Sign-On (IAM Identity AWS Managed Microsoft AD Center) authentifiziert wurden.


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

Weitere Informationen zur Verwendung dieser Operation finden Sie unter GetSessionEmbedUrl. Sie können diese und andere API-Operationen in Ihrem eigenen Code verwenden.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Schritt 1: Festlegen von Berechtigungen

Schritt 3: Einbetten der URL