users

Creates, updates, deletes, gets or lists a users resource.

Overview

Name	users
Type	Resource
Id	aws.quicksight.users

Fields

The following fields are returned by SELECT queries:

describe_user

Name	Datatype	Description
request_id	string	The Amazon Web Services request ID for this operation.
status	integer	The HTTP status of the request.
user	object	The user name.

list_users

Name	Datatype	Description
active	boolean	The active status of user. When you create an Quick Sight user that's not an IAM user or an Active Directory user, that user is inactive until they sign in and provide a password.
arn	string	The Amazon Resource Name (ARN) for the user.
custom_permissions_name	string	The custom permissions profile associated with this user. (pattern: <code>^[a-zA-Z0-9+=,.@_-]+$</code>)
email	string	The user's email address.
external_login_federation_provider_type	string	The type of supported external login provider that provides identity to let the user federate into Quick Sight with an associated IAM role. The type can be one of the following. COGNITO: Amazon Cognito. The provider URL is cognito-identity.amazonaws.com. CUSTOM_OIDC: Custom OpenID Connect (OIDC) provider.
external_login_federation_provider_url	string	The URL of the external login provider.
external_login_id	string	The identity ID for the user in the external login provider.
identity_type	string	The type of identity authentication used by the user. (IAM, QUICKSIGHT, IAM_IDENTITY_CENTER)
principal_id	string	The principal ID of the user.
role	string	The Quick Sight role for the user. The user role can be one of the following:. READER: A user who has read-only access to dashboards. AUTHOR: A user who can create data sources, datasets, analyses, and dashboards. ADMIN: A user who is an author, who can also manage Amazon Quick Sight settings. READER_PRO: Reader Pro adds Generative BI capabilities to the Reader role. Reader Pros have access to Amazon Q in Quick Sight, can build stories with Amazon Q, and can generate executive summaries from dashboards. AUTHOR_PRO: Author Pro adds Generative BI capabilities to the Author role. Author Pros can author dashboards with natural language with Amazon Q, build stories with Amazon Q, create Topics for Q&A, and generate executive summaries from dashboards. ADMIN_PRO: Admin Pros are Author Pros who can also manage Quick Sight administrative settings. Admin Pro users are billed at Author Pro pricing. RESTRICTED_READER: This role isn't currently available for use. RESTRICTED_AUTHOR: This role isn't currently available for use. (ADMIN, AUTHOR, READER, RESTRICTED_AUTHOR, RESTRICTED_READER, ADMIN_PRO, AUTHOR_PRO, READER_PRO)
user_name	string	The user's user name. This value is required if you are registering a user that will be managed in Quick Sight. In the output, the value for UserName is N/A when the value for IdentityType is IAM and the corresponding IAM user is deleted. (pattern: <code>[\u0020-\u00FF]+</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_user	select	user_name, aws_account_id, namespace, region		Returns information about a user, given the user name.
list_users	select	aws_account_id, namespace, region	next-token, max-results	Returns a list of all of the Amazon Quick Sight users belonging to this account.
register_user	insert	aws_account_id, namespace, region, IdentityType, UserRole		Creates an Amazon Quick Sight user whose identity is associated with the Identity and Access Management (IAM) identity or role specified in the request. When you register a new user from the Quick Sight API, Quick Sight generates a registration URL. The user accesses this registration URL to create their account. Quick Sight doesn't send a registration email to users who are registered from the Quick Sight API. If you want new users to receive a registration email, then add those users in the Quick Sight console. For more information on registering a new user in the Quick Sight console, see Inviting users to access Quick Sight.
update_user	update	user_name, aws_account_id, namespace, region		Updates an Amazon Quick Sight user.
delete_user	delete	user_name, aws_account_id, namespace, region		Deletes the Amazon Quick Sight user that is associated with the identity of the IAM user or role that's making the call. The IAM user isn't deleted as a result of this call.
delete_user_by_principal_id	delete	principal_id, aws_account_id, namespace, region		Deletes a user identified by its principal ID.
generate_embed_url_for_registered_user	exec	aws_account_id, region, UserArn, ExperienceConfiguration		Generates an embed URL that you can use to embed an Amazon Quick experience in your website. This action can be used for any type of user registered in an Amazon Quick account. Before you use this action, make sure that you have configured the relevant Amazon Quick resource and permissions. The following rules apply to the generated URL: It contains a temporary bearer token. It is valid for 5 minutes after it is generated. Once redeemed within this period, it cannot be re-used again. The URL validity period should not be confused with the actual session lifetime that can be customized using the SessionLifetimeInMinutes parameter. The resulting user session is valid for 15 minutes (minimum) to 10 hours (maximum). The default session duration is 10 hours. You are charged only when the URL is used or there is interaction with Amazon Quick. For more information, see Embedded Analytics in the Amazon Quick User Guide. For more information about the high-level steps for embedding and for an interactive demo of the ways you can customize embedding, visit the Amazon Quick Developer Portal.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
aws_account_id	string	The ID for the Amazon Web Services account that contains the dashboard that you're embedding.
namespace	string	The namespace. Currently, you should set this to default.
principal_id	string	The principal ID of the user.
region	string	AWS region (default: us-east-1)
user_name	string	The name of the user that you want to delete.
max-results	integer	The maximum number of results to return from this request.
next-token	string	A pagination token that can be used in a subsequent request.

SELECT examples

describe_user

Returns information about a user, given the user name.

SELECT
request_id,
status,
user
FROM aws.quicksight.users
WHERE user_name = '{{ user_name }}' -- required
AND aws_account_id = '{{ aws_account_id }}' -- required
AND namespace = '{{ namespace }}' -- required
AND region = '{{ region }}' -- required
;

list_users

Returns a list of all of the Amazon Quick Sight users belonging to this account.

SELECT
active,
arn,
custom_permissions_name,
email,
external_login_federation_provider_type,
external_login_federation_provider_url,
external_login_id,
identity_type,
principal_id,
role,
user_name
FROM aws.quicksight.users
WHERE aws_account_id = '{{ aws_account_id }}' -- required
AND namespace = '{{ namespace }}' -- required
AND region = '{{ region }}' -- required
AND `next-token` = '{{ next-token }}'
AND `max-results` = '{{ max-results }}'
;

INSERT examples

register_user

Creates an Amazon Quick Sight user whose identity is associated with the Identity and Access Management (IAM) identity or role specified in the request. When you register a new user from the Quick Sight API, Quick Sight generates a registration URL. The user accesses this registration URL to create their account. Quick Sight doesn't send a registration email to users who are registered from the Quick Sight API. If you want new users to receive a registration email, then add those users in the Quick Sight console. For more information on registering a new user in the Quick Sight console, see Inviting users to access Quick Sight.

INSERT INTO aws.quicksight.users (
IdentityType,
Email,
UserRole,
IamArn,
SessionName,
UserName,
CustomPermissionsName,
ExternalLoginFederationProviderType,
CustomFederationProviderUrl,
ExternalLoginId,
Tags,
aws_account_id,
namespace,
region
)
SELECT 
'{{ IdentityType }}' /* required */,
'{{ Email }}',
'{{ UserRole }}' /* required */,
'{{ IamArn }}',
'{{ SessionName }}',
'{{ UserName }}',
'{{ CustomPermissionsName }}',
'{{ ExternalLoginFederationProviderType }}',
'{{ CustomFederationProviderUrl }}',
'{{ ExternalLoginId }}',
'{{ Tags }}',
'{{ aws_account_id }}',
'{{ namespace }}',
'{{ region }}'
RETURNING
request_id,
status,
user,
user_invitation_url
;

Manifest

# Description fields are for documentation purposes
- name: users
props:
  - name: aws_account_id
    value: "{{ aws_account_id }}"
    description: Required parameter for the users resource.
  - name: namespace
    value: "{{ namespace }}"
    description: Required parameter for the users resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the users resource.
  - name: IdentityType
    value: "{{ IdentityType }}"
    valid_values: ['IAM', 'QUICKSIGHT', 'IAM_IDENTITY_CENTER']
  - name: Email
    value: "{{ Email }}"
  - name: UserRole
    value: "{{ UserRole }}"
    valid_values: ['ADMIN', 'AUTHOR', 'READER', 'RESTRICTED_AUTHOR', 'RESTRICTED_READER', 'ADMIN_PRO', 'AUTHOR_PRO', 'READER_PRO']
  - name: IamArn
    value: "{{ IamArn }}"
  - name: SessionName
    value: "{{ SessionName }}"
  - name: UserName
    value: "{{ UserName }}"
  - name: CustomPermissionsName
    value: "{{ CustomPermissionsName }}"
  - name: ExternalLoginFederationProviderType
    value: "{{ ExternalLoginFederationProviderType }}"
  - name: CustomFederationProviderUrl
    value: "{{ CustomFederationProviderUrl }}"
  - name: ExternalLoginId
    value: "{{ ExternalLoginId }}"
  - name: Tags
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"

UPDATE examples

update_user

Updates an Amazon Quick Sight user.

UPDATE aws.quicksight.users
SET 
Email = '{{ Email }}',
Role = '{{ Role }}',
CustomPermissionsName = '{{ CustomPermissionsName }}',
UnapplyCustomPermissions = {{ UnapplyCustomPermissions }},
ExternalLoginFederationProviderType = '{{ ExternalLoginFederationProviderType }}',
CustomFederationProviderUrl = '{{ CustomFederationProviderUrl }}',
ExternalLoginId = '{{ ExternalLoginId }}'
WHERE 
user_name = '{{ user_name }}' --required
AND aws_account_id = '{{ aws_account_id }}' --required
AND namespace = '{{ namespace }}' --required
AND region = '{{ region }}' --required
RETURNING
request_id,
status,
user;

DELETE examples

delete_user

Deletes the Amazon Quick Sight user that is associated with the identity of the IAM user or role that's making the call. The IAM user isn't deleted as a result of this call.

DELETE FROM aws.quicksight.users
WHERE user_name = '{{ user_name }}' --required
AND aws_account_id = '{{ aws_account_id }}' --required
AND namespace = '{{ namespace }}' --required
AND region = '{{ region }}' --required
;

delete_user_by_principal_id

Deletes a user identified by its principal ID.

DELETE FROM aws.quicksight.users
WHERE principal_id = '{{ principal_id }}' --required
AND aws_account_id = '{{ aws_account_id }}' --required
AND namespace = '{{ namespace }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

generate_embed_url_for_registered_user

Generates an embed URL that you can use to embed an Amazon Quick experience in your website. This action can be used for any type of user registered in an Amazon Quick account. Before you use this action, make sure that you have configured the relevant Amazon Quick resource and permissions. The following rules apply to the generated URL: It contains a temporary bearer token. It is valid for 5 minutes after it is generated. Once redeemed within this period, it cannot be re-used again. The URL validity period should not be confused with the actual session lifetime that can be customized using the SessionLifetimeInMinutes parameter. The resulting user session is valid for 15 minutes (minimum) to 10 hours (maximum). The default session duration is 10 hours. You are charged only when the URL is used or there is interaction with Amazon Quick. For more information, see Embedded Analytics in the Amazon Quick User Guide. For more information about the high-level steps for embedding and for an interactive demo of the ways you can customize embedding, visit the Amazon Quick Developer Portal.

EXEC aws.quicksight.users.generate_embed_url_for_registered_user 
@aws_account_id='{{ aws_account_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"SessionLifetimeInMinutes": {{ SessionLifetimeInMinutes }}, 
"UserArn": "{{ UserArn }}", 
"ExperienceConfiguration": "{{ ExperienceConfiguration }}", 
"AllowedDomains": "{{ AllowedDomains }}"
}'
;