Étape 2 : Générer l'URL avec le code d'authentification en pièce jointe

Dans la section suivante, vous découvrirez comment authentifier votre utilisateur et obtenir l'URL de tableau de bord intégrable sur votre serveur d'applications. Si vous prévoyez d'intégrer des tableaux de bord pour les types IAM ou QuickSight d'identité, partagez-les avec les utilisateurs.

Lorsqu'un utilisateur accède à votre application, l'application assume le rôle IAM pour le compte de l'utilisateur. Ensuite, il ajoute l'utilisateur à QuickSight, si cet utilisateur n'existe pas déjà. Puis, elle transmet un identifiant comme ID de session de rôle unique.

L'exécution de ces étapes garantit que chaque utilisateur du tableau de bord est approvisionné de manière unique. QuickSight Elle applique également les paramètres par utilisateur, tels que les valeurs dynamiques et de sécurité par défaut au niveau des lignes pour les paramètres.

Les exemples suivants effectuent l'authentification IAM pour le compte de l'utilisateur. Ce code s'exécute sur votre serveur d'applications.

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.GenerateEmbedUrlForRegisteredUserRequest;
    import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult;
    import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration;
    import com.amazonaws.services.quicksight.model.RegisteredUserDashboardEmbeddingConfiguration;

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

        private final AmazonQuickSight quickSightClient;

        public GetQuicksightEmbedUrlRegisteredUserDashboardEmbedding() {
            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, // AWS Account ID
                final String dashboardId, // Dashboard ID to embed
                final List<String> allowedDomains, // Runtime allowed domain for embedding
                final String userArn // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find out how to get user arn for a QuickSight user.
        ) throws Exception {
            final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration()
                    .withDashboard(new RegisteredUserDashboardEmbeddingConfiguration().withInitialDashboardId(dashboardId));
            final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();
            generateEmbedUrlForRegisteredUserRequest.setAwsAccountId(accountId);
            generateEmbedUrlForRegisteredUserRequest.setUserArn(userArn);
            generateEmbedUrlForRegisteredUserRequest.setAllowedDomains(allowedDomains);
            generateEmbedUrlForRegisteredUserRequest.setExperienceConfiguration(experienceConfiguration);

            final GenerateEmbedUrlForRegisteredUserResult generateEmbedUrlForRegisteredUserResult = quickSightClient.generateEmbedUrlForRegisteredUser(generateEmbedUrlForRegisteredUserRequest);

            return generateEmbedUrlForRegisteredUserResult.getEmbedUrl();
        }
    }

JavaScript

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

    function generateEmbedUrlForRegisteredUser(
        accountId,
        dashboardId,
        openIdToken, // Cognito-based token
        userArn, // registered user arn
        roleArn, // IAM user role to use for embedding
        sessionName, // Session name for the roleArn assume role
        allowedDomains, // Runtime allowed domain for embedding
        getEmbedUrlCallback, // GetEmbedUrl success callback method
        errorCallback // GetEmbedUrl error callback method
        ) {
        const stsClient = new AWS.STS();
        let stsParams = {
            RoleSessionName: sessionName,
            WebIdentityToken: openIdToken,
            RoleArn: roleArn
        }

        stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
            if (err) {
                console.log('Error assuming role');
                console.log(err, err.stack);
                errorCallback(err);
            } else {
                const getDashboardParams = {
                    "AwsAccountId": accountId,
                    "ExperienceConfiguration": {
                        "Dashboard": {
                            "InitialDashboardId": dashboardId
                        }
                    },
                    "UserArn": userArn,
                    "AllowedDomains": allowedDomains,
                    "SessionLifetimeInMinutes": 600
                };

                const quicksightClient = new AWS.QuickSight({
                    region: process.env.AWS_REGION,
                    credentials: {
                        accessKeyId: data.Credentials.AccessKeyId,
                        secretAccessKey: data.Credentials.SecretAccessKey,
                        sessionToken: data.Credentials.SessionToken,
                        expiration: data.Credentials.Expiration
                    }
                });

                quicksightClient.generateEmbedUrlForRegisteredUser(getDashboardParams, 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

    sts = boto3.client('sts')

    # Function to generate embedded URL  
    # accountId: AWS account ID
    # dashboardId: Dashboard ID to embed
    # userArn: arn of registered user
    # allowedDomains: Runtime allowed domain for embedding
    # openIdToken: Token to assume role with roleArn
    # roleArn: IAM user role to use for embedding
    # sessionName: session name for the roleArn assume role
    def getEmbeddingURL(accountId, dashboardId, userArn, allowedDomains, openIdToken, roleArn, sessionName):
        try:
            assumedRole = sts.assume_role(
                RoleArn = roleArn,
                RoleSessionName = sessionName,
                WebIdentityToken = openIdToken
            )
        except ClientError as e:
            return "Error assuming role: " + str(e)
        else: 
            assumedRoleSession = boto3.Session(
                aws_access_key_id = assumedRole['Credentials']['AccessKeyId'],
                aws_secret_access_key = assumedRole['Credentials']['SecretAccessKey'],
                aws_session_token = assumedRole['Credentials']['SessionToken'],
            )
            try:
                quickSightClient = assumedRoleSession.client('quicksight', region_name='us-east-1')
                
                response = quickSightClient.generate_embed_url_for_registered_user(
                    "AwsAccountId" = accountId,
                    "ExperienceConfiguration" = {
                        "Dashboard" = {
                            "InitialDashboardId" = dashboardId
                        }
                    },
                    "UserArn" = userArn,
                    "AllowedDomains" = allowedDomains,
                    "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:
                return "Error generating embedding url: " + str(e)

Node.js

L'exemple suivant montre le JavaScript (Node.js) que vous pouvez utiliser sur le serveur d'applications pour générer l'URL du tableau de bord intégré. Vous pouvez utiliser cette URL dans votre site Web ou votre application pour afficher le tableau de bord.

const AWS = require('aws-sdk');
    const https = require('https');

    var quicksightClient = new AWS.Service({
        apiConfig: require('./quicksight-2018-04-01.min.json'),
        region: 'us-east-1',
    });

    quicksightClient.generateEmbedUrlForRegisteredUser({
        'AwsAccountId': '111122223333',
        'ExperienceConfiguration': { 
            'Dashboard': {
                'InitialDashboardId': '1c1fe111-e2d2-3b30-44ef-a0e111111cde'
            }
        },
        'UserArn': 'REGISTERED_USER_ARN',
        'AllowedDomains': allowedDomains,
        'SessionLifetimeInMinutes': 100
    }, 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://quicksightdomain/embed/12345/dashboards/67890...'
            RequestId: '7bee030e-f191-45c4-97fe-d9faf0e03713' 
        }

.NET/C#

L'exemple suivant montre le code .NET/C # que vous pouvez utiliser sur le serveur d'applications afin de générer l'URL pour le tableau de bord intégré. Vous pouvez utiliser cette URL dans votre site Web ou votre application pour afficher le tableau de bord.

using System;
    using Amazon.QuickSight;
    using Amazon.QuickSight.Model;

    namespace GenerateDashboardEmbedUrlForRegisteredUser
    {
        class Program
        {
            static void Main(string[] args)
            {
                var quicksightClient = new AmazonQuickSightClient(
                    AccessKey,
                    SecretAccessKey,
                    SessionToken,
                    Amazon.RegionEndpoint.USEast1);
                try
                {
                    RegisteredUserDashboardEmbeddingConfiguration registeredUserDashboardEmbeddingConfiguration
                        = new RegisteredUserDashboardEmbeddingConfiguration
                        {
                            InitialDashboardId = "dashboardId"
                        };
                    RegisteredUserEmbeddingExperienceConfiguration registeredUserEmbeddingExperienceConfiguration
                        = new RegisteredUserEmbeddingExperienceConfiguration
                        {
                            Dashboard = registeredUserDashboardEmbeddingConfiguration
                        };
                        
                    Console.WriteLine(
                        quicksightClient.GenerateEmbedUrlForRegisteredUserAsync(new GenerateEmbedUrlForRegisteredUserRequest
                        {
                            AwsAccountId = "111122223333",
                            ExperienceConfiguration = registeredUserEmbeddingExperienceConfiguration,
                            UserArn = "REGISTERED_USER_ARN",
                            AllowedDomains = allowedDomains,
                            SessionLifetimeInMinutes = 100
                        }).Result.EmbedUrl
                    );
                } catch (Exception ex) {
                    Console.WriteLine(ex.Message);
                }
            }
        }
    }

AWS CLI

Pour assumer ce rôle, choisissez l'une des opérations d'API AWS Security Token Service (AWS STS) suivantes :

• AssumeRole— Utilisez cette opération lorsque vous utilisez une identité IAM pour assumer le rôle.

• AssumeRoleWithWebIdentity— Utilisez cette opération lorsque vous utilisez un fournisseur d'identité Web pour authentifier votre utilisateur.

• AssumeRoleWithSaml— Utilisez cette opération lorsque vous utilisez le protocole SAML pour authentifier vos utilisateurs.

L'exemple suivant illustre la commande de l'interface de ligne de commande pour définir le rôle IAM. Les autorisations doivent être activées pour quicksight:GenerateEmbedUrlForRegisteredUser. Si vous envisagez d'ajouter des utilisateurs lorsqu'ils ouvrent un just-in-time tableau de bord pour la première fois, les autorisations doivent également être activées pour le rôlequicksight:RegisterUser.

aws sts assume-role \
        --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \
        --role-session-name [e-mail]

L'opération assume-role renvoie trois paramètres de sortie : la clé d'accès, la clé secrète et le jeton de session.

Note

Si vous obtenez une erreur ExpiredToken lorsque vous appelez l'opération AssumeRole, ceci est probablement dû au fait que le précédent SESSION TOKEN est encore dans les variables de l'environnement. Pour l'effacer, définissez les variables suivantes :

• AWS_ACCESS_KEY_ID

• AWS_SECRET_ACCESS_KEY

• AWS_SESSION_TOKEN

L'exemple suivant montre comment définir ces trois paramètres dans l'interface de ligne de commande. Si vous utilisez une machine Microsoft Windows, utilisez set au lieu de 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'exécution de ces commandes définit l'ID de session de rôle de l'utilisateur visitant votre site web sur embedding_quicksight_dashboard_role/[e-mail]. L'ID de session de rôle se compose du nom de rôle issu du role-arn et de la valeur role-session-name. L'utilisation de l'ID de session de rôle unique pour chaque utilisateur garantit que les autorisations appropriées sont définies pour chaque utilisateur. Ceci évite également toute limitation des accès des utilisateurs. La limitation est une fonctionnalité de sécurité qui empêche le même utilisateur d'accéder à partir de plusieurs QuickSight emplacements.

L'ID de session du rôle devient également le nom d'utilisateur dans QuickSight. Vous pouvez utiliser ce modèle pour approvisionner vos utilisateurs à l' QuickSight avance ou pour les configurer la première fois qu'ils accèdent au tableau de bord.

L'exemple suivant montre la commande de l'interface de ligne de commande que vous pouvez utiliser pour provisionner un utilisateur. Pour plus d'informations sur RegisterUserDescribeUser, et d'autres opérations d' QuickSight API, consultez la référence des QuickSight API.

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 "[e-mail]" \
        --email [e-mail] \
        --region us-east-1 \
        --custom-permissions-name TeamA1

Si votre utilisateur est authentifié via Microsoft AD, vous n'avez pas besoin d'utiliser RegisterUser pour le configurer. Au lieu de cela, ils devraient être automatiquement abonnés lors de leur premier accès QuickSight. Pour les utilisateurs Microsoft AD, vous pouvez utiliser DescribeUser pour obtenir l'ARN de l'utilisateur.

La première fois qu'un utilisateur accède QuickSight, vous pouvez également l'ajouter au groupe avec lequel le tableau de bord est partagé. L'exemple suivant montre la commande de l'interface de ligne de commande pour ajouter un utilisateur à un groupe.

aws quicksight create-group-membership \
        --aws-account-id=111122223333 \
        --namespace=default \
        --group-name=financeusers \
        --member-name="embedding_quicksight_dashboard_role/[e-mail]"

Vous avez désormais un utilisateur de votre application qui est également un utilisateur du QuickSight tableau de bord et qui a accès à celui-ci.

Enfin, pour obtenir une URL signée pour le tableau de bord, appelez generate-embed-url-for-registered-user à partir du serveur d'applications. Ceci renvoie l'URL du tableau de bord intégrable. L'exemple suivant montre comment générer l'URL d'un tableau de bord intégré à l'aide d'un appel côté serveur pour les utilisateurs authentifiés par le biais de l'authentification unique (IAM AWS Managed Microsoft AD Identity Center).

aws quicksight generate-embed-url-for-registered-user \
        --aws-account-id 111122223333 \
        --session-lifetime-in-minutes 600 \
        --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_visual_role/embeddingsession \
        --allowed-domains '["domain1","domain2"]' \
        --experience-configuration Dashboard={InitialDashboardId=1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89}
    

Pour plus d'informations sur l'utilisation de cette opération, consultez GenerateEmbedUrlForRegisteredUser. Vous pouvez utiliser cette opération et d'autres opérations d'API dans votre propre code.