Skip to content

How to Add or Remove Users and User Groups in AWS Quicksight

Jump to bottom
Billie Rose edited this page Dec 18, 2023 · 1 revision

Prerequisites

  • Access to the BFD AWS Account
  • IAM permissions to decrypt sensitive SSM parameters
  • An installation of the AWS CLI that is configured properly for access to the BFD/CMS AWS account
  • An installation of the terraform CLI
    • Using a tool like tfenv allows for multiple installations of Terraform and automatic version management
  • Your EDITOR environment variable set to a proper editor
    • You can set this variable in your .bashrc (if you're using bash) or .zshrc (if you're using zsh) like so: export EDITOR=<your editor executable here>. Other shells may have a different syntax for setting environment variables or a different configuration file
  • This repository, beneficiary-fhir-data, pulled down locally

How to Make Changes to the mgmt Environment

Adding or removing users and user groups from AWS Quicksight will require modifying the mgmt environment. You will need to follow the steps below prior to making any modifications.

  1. In your terminal, navigate to the root of your local copy of the beneficiary-fhir-data repository using cd

  2. In your terminal, relative to the root of this repository, cd to the directory associated with the mgmt Terraform module:

    cd ops/terraform/env/mgmt

  3. Initialize the Terraform state locally:

    terraform init

  4. Once initialized, view the Terraform plan and verify that Terraform is able to load state for all of the resources managed by the mgmt module and that no changes are necessary:

    terraform plan

  5. Navigate into the base_config module's directory:

    cd base_config

  6. Ensure you are authenticated with AWS and are able to run AWS CLI commands

  7. Open the encrypted yaml mgmt.eyaml for editing using the edit-eyaml.sh script using the commands below. This will decrypt the encrypted mgmt.eyaml file and open it in your defined EDITOR. The script will wait until the file is closed by your editor, at which point it will re-encrypt mgmt.eyaml with your changes and save it

    chmod +x scripts/edit-eyaml.sh
scripts/edit-eyaml.sh mgmt

  8. You will see the following keys grouped together in the format shown below.

    /bfd/mgmt/quicksight/sensitive/principal_admin_arn: str
/bfd/mgmt/quicksight/sensitive/users: encoded JSON Array
/bfd/mgmt/quicksight/sensitive/groups: encoded JSON Array
    1. principal_admin_arn is the fall-back arn of the user or group that will become the owner of assets that are solely owned by any user being deleted.
    2. users is an encoded JSON array of Quicksight users expected to adhere to the following format:
    [{"email":"some.email@email.com", "user_role":"AUTHOR|ADMIN|READER", "identity_type":"QUICKSIGHT|IAM","groups":[""]}]

    If IAM is specified as the identity_type, then iam_arn must be provided as an attribute. If QUICKSIGHT is specified as the identity_type, then user_name must be provided as an attribute.

    1. groups is an encoded JSON array of Quicksight groups expected to adhere to the following format:
    [{"group_name":"abbrv-readers"}]

    group_name should have a prefix describing the org or partner and a suffix describing the group's role (i.e. -readers, -owners

  9. Refer to the instructions below and follow its steps to add or remove users and user groups from AWS Quicksight.

Instructions

How to Add a User to AWS Quicksight

It is recommended that you read the following READMEs for more information on the SSM configuration scheme used by BFD before continuing:

Additionally:

  • You will need to know the user's email and IAM (if the user has one). IAM is not a requirement.
  • You will need to know the assets that the user will need access to via their assigned group(s). E.g., bcda, bfd, etc.
  • You will need to know the user's role - READER or AUTHOR or ADMIN
  1. After following the instructions to modify the mgmt environment outlined in the prerequisites above, append the new user in its correct json format to the array defined in /bfd/mgmt/quicksight/sensitive/users
  2. Close the file. This should immediately update the encrypted mgmt.eyaml with your new changes
  3. Refer to How to Apply Your Changes to complete the addition.
  4. If the user you've added is NOT an IAM user, you will need to send an invitation to the user's email. The only way to do so is via the AWS Quicksight console.
    1. Sign-in to the AWS Quicksight Console
    2. In the upper-right corner, click on the user icon
    3. Select "Manage Quicksight"
    4. Find the new user and click their corresponding Reset password link. The user should receive an email with the subject Invitation to Join QuickSight. They will have 7 days to accept the invitation.

How to Remove a User from AWS Quicksight

It is recommended that you read the following READMEs for more information on the SSM configuration scheme used by BFD before continuing:

  1. After following the instructions to modify the mgmt environment outlined in the prerequisites above, find the user's corresponding json object in /bfd/mgmt/quicksight/sensitive/users by their email or IAM.
  2. Simply remove the user's json object from the json array.
  3. Close the file. This should immediately update the encrypted mgmt.eyaml with your new changes
  4. Refer to How to Apply Your Changes to complete the removal.

How to Add a User Group to AWS Quicksight

It is recommended that you read the following READMEs for more information on the SSM configuration scheme used by BFD before continuing:

  1. After following the instructions to modify the mgmt environment outlined in the prerequisites above, append the new group in its correct json format to the array defined in /bfd/mgmt/quicksight/sensitive/groups
  2. Close the file. This should immediately update the encrypted mgmt.eyaml with your new changes
  3. Refer to How to Apply Your Changes to complete the addition.

How to Remove a User Group from AWS Quicksight

It is recommended that you read the following READMEs for more information on the SSM configuration scheme used by BFD before continuing:

  1. After following the instructions to modify the mgmt environment outlined in the prerequisites above, find the group's corresponding json object in /bfd/mgmt/quicksight/sensitive/groups
  2. Simply remove the group's json object from the json array.
  3. Close the file. This should immediately update the encrypted mgmt.eyaml with your new changes
  4. Refer to How to Apply Your Changes to complete the removal.

How to Update the Default Owner for Assets Whose Owner was Deleted

It is recommended that you read the following READMEs for more information on the SSM configuration scheme used by BFD before continuing:

Additionally:

  • The arn of the user or group that will become the owner of assets that are solely owned by any user being deleted.
  1. After following the instructions to modify the mgmt environment outlined in the prerequisites above, simply update the arn for principal_admin_arn.
  2. Close the file. This should immediately update the encrypted mgmt.eyaml with your new changes
  3. Refer to How to Apply Your Changes to complete the update.

How to Apply Your Changes

  1. Return to the mgmt module:

    cd ..

  2. Plan the changes to the Terraform state and verify that there are only removals from the state and that these removals correspond to the changes made in step #9:

    terraform plan

  3. Open a new Pull Request with the changes to all configuration in the associated branch

  4. Once approved, the changes to mgmt can be applied:

    1. From the root of the repository, cd into the mgmt module:

      cd ops/terraform/env/mgmt

    2. Apply the changes to configuration ensuring that there are no unexpected changes:

      terraform apply
For BFD Contributors and Maintainers
Clone this wiki locally