How to Add or Remove User SSH Access

How to Add or Remove Users' SSH Access

• How to Add or Remove Users' SSH Access
  • Prerequisites
  • Instructions
    • How to Add a New User's SSH Key and Configure Access
    • How to Remove a User's SSH Access

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 ansible CLI
• 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

Instructions

How to Add a New User's SSH Key and Configure Access

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

• mgmt's base_config README
• base service README

Additionally:

• You will need to know the user's EUA
• You will need the user's SSH public key and desired username
• You will need to know the level of access the user has to each established environment and whether they should be given access by default

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.yaml for editing using the edit-yaml.sh script using the commands below. This will decrypt the encrypted mgmt.yaml 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.yaml with your changes and save it

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

8. You will see many keys grouped together in the format shown below. In the example below, .... represents each user's EUA ID. Each key represents the following:

   1. ssh_user represents the user's SSH username that they will use to connect to a machine using their key
   2. ssh_public_key represents the public key component of the user's key-pair. This must be generated by the user themselves and provided to you
   3. ssh_default_access defines whether the user has access, by default, to connect via SSH to any BFD instance in any environment. Essentially, this overrides per-environment access for a given user and should be set to true for users that require access in all environments (such as those in our on-call rotation)
   4. ssh_default_sudoer defines whether the user has sudoer permission, by default, for any BFD instance in any environment. Essentially, this overrides per-environment sudoer access for a given user and should only be set to true for users that need access to sudo in all environments (such as those in our on-call rotation)

   /bfd/mgmt/common/sensitive/user/..../ssh_user: "some.username"
   /bfd/mgmt/common/sensitive/user/..../ssh_public_key: "ssh-key .... identity"
   /bfd/mgmt/common/sensitive/user/..../ssh_default_access: bool
   /bfd/mgmt/common/sensitive/user/..../ssh_default_sudoer: bool

9. Following the format outlined in step #8, append the new user's ssh_user, ssh_public_key, ssh_default_access, and ssh_default_sudoer values (depending on their required level of access) to the end of the block associated with SSH. Remember, you will need the user's EUA as it is part of the SSM parameter's path

10. Close the file. This should immediately update the encrypted mgmt.yaml with your new changes

11. Return to the mgmt module:

    cd ..

12. Plan the changes to the Terraform state and verify that there are only additions to the state and that these additions correspond to the new SSH SSM parameters defined in step #9:

    terraform plan

13. Now that the user's username and SSH public key are set in the mgmt environment, the user's SSH access and sudoer access can be defined per-environment. If the user has been given default access to SSH and to use sudo then steps #14 through #22 can be skipped as the user does not need to be configured in our established environments

14. From the root of the repository, navigate to the base Terraform service module:

    cd ops/terraform/services/base

15. Once again, initialize the module:

    terraform init

16. Then, select the workspace corresponding to the environment you are provisioning the user's access for:

    terraform workspace select <prod|prod-sbx|test>

17. Then, run the plan and verify that all of base's resources are found and that there are no changes:

    terraform plan

18. Similarly to step #7, use the edit-yaml.sh to open the corresponding environment's .yaml in your defined EDITOR:

    chmod +x scripts/edit-yaml.sh
    scripts/edit-yaml.sh <prod|prod-sbx|test>

19. Find the block of SSM keys corresponding to SSH, or, if the block of keys do not yet exist, append the below to the end of the file. .... should be replaced with the user's EUA ID. What each key represents is as follows:

    1. ssh_access defines whether the user has the ability to SSH into instances launched in the current environment. If this is false, the user will not have the ability to SSH into any instance, whereas if this is true the user will be able to SSH. Note that this is overridden by ssh_default_access (in the mgmt "environment") if ssh_default_access is true. Omission is treated as false
    2. ssh_sudoer defines whether the user has the ability to run sudo and act as root on instances launched in the current environment. If this is false, the user will not have the ability to run sudo and act as root, whereas if this is true the user will be able to do so. Note that this is overridden by ssh_default_sudoer (in the mgmt "environment") if ssh_default_sudoer is true. Omission is treated as false

    /bfd/${env}/common/sensitive/user/..../ssh_access: bool
    /bfd/${env}/common/sensitive/user/..../ssh_sudoer: bool

20. Close the file. This will save your changes and re-encrypt the encrypted YAML file for the current environment.

21. Plan the changes to the Terraform state and verify that there are only additions to the state and that these additions correspond to the new SSH SSM parameters defined in step #20:

    terraform plan

22. Repeat steps #14 through #21 for each environment that the user should be provisioned in

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

24. 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

25. Once approved, the changes to each established environment can also be applied:

    1. cd into the base service Terraform module:

       cd ops/terraform/services/base

    2. Switch to the current environment's corresponding workspace:

       terraform workspace select <prod|prod-sbx|test>

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

       terraform apply

    4. Repeat the above steps for each established environment that was changed

26. Once finished, the new user will be fully provisioned the next time the Build App AMIs stage is run in our deployment pipeline. In the meantime, anytime a brand new instance is launched the new user will be able to SSH into it assuming either ssh_default_access is true or if, for the instance's environment, ssh_access is true

How to Remove a User's SSH Access

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

• mgmt's base_config README
• base service README

Additionally:

• You will need to know the user's EUA

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.yaml for editing using the edit-yaml.sh script using the commands below. This will decrypt the encrypted mgmt.yaml 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.yaml with your changes and save it

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

8. You will see many keys grouped together in the format shown below. In the example below, .... represents each user's EUA ID. Each key represents the following:

   1. ssh_user represents the user's SSH username that they will use to connect to a machine using their key
   2. ssh_public_key represents the public key component of the user's key-pair
   3. ssh_default_access defines whether the user has access, by default, to connect via SSH to any BFD instance in any environment. Essentially, this overrides per-environment access for a given user and should be set to true for users that require access in all environments (such as those in our on-call rotation)
   4. ssh_default_sudoer defines whether the user has sudoer permission, by default, for any BFD instance in any environment. Essentially, this overrides per-environment sudoer access for a given user and should only be set to true for users that need access to sudo in all environments (such as those in our on-call rotation)

   /bfd/mgmt/common/sensitive/user/..../ssh_user: "some.username"
   /bfd/mgmt/common/sensitive/user/..../ssh_public_key: "ssh-key .... identity"
   /bfd/mgmt/common/sensitive/user/..../ssh_default_access: bool
   /bfd/mgmt/common/sensitive/user/..../ssh_default_sudoer: bool

9. Knowing the user's EUA, find their corresponding SSM keys and do one of the following to disable their SSH access:

   1. Simply delete all of the keys associated with the user. This will remove their access globally and should be done if the user is no longer a contributor to BFD. You will still need to check each established environment in order to remove any orphaned SSM keys for environment-specific access
   2. Set ssh_default_access to false. This will disable default access, so you will still need to follow the proceeding steps to modify ssh_access in all established environments to remove their access completely

10. Close the file. This should immediately update the encrypted mgmt.yaml with your new changes

11. Return to the mgmt module:

    cd ..

12. 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

13. Now that the user's access has been removed in the global mgmt module, you will need to check each established environment's configuration to ensure that their access is removed from each

14. From the root of the repository, navigate to the base Terraform service module:

    cd ops/terraform/services/base

15. Once again, initialize the module:

    terraform init

16. Then, select the workspace corresponding to the environment you are modifying the user's access for:

    terraform workspace select <prod|prod-sbx|test>

17. Then, run the plan and verify that all of base's resources are found and that there are no changes:

    terraform plan

18. Similarly to step #7, use the edit-yaml.sh to open the corresponding environment's .yaml in your defined EDITOR:

    chmod +x scripts/edit-yaml.sh
    scripts/edit-yaml.sh <prod|prod-sbx|test>

19. Find the block of SSM keys corresponding to SSH, or, if the block of keys do not yet exist, you can skip to step #23. .... should be replaced with the user's EUA ID. What each key represents is as follows:

    1. ssh_access defines whether the user has the ability to SSH into instances launched in the current environment. If this is false, the user will not have the ability to SSH into any instance, whereas if this is true the user will be able to SSH. Note that this is overridden by ssh_default_access (in the mgmt "environment") if ssh_default_access is true. Omission is treated as false
    2. ssh_sudoer defines whether the user has the ability to run sudo and act as root on instances launched in the current environment. If this is false, the user will not have the ability to run sudo and act as root, whereas if this is true the user will be able to do so. Note that this is overridden by ssh_default_sudoer (in the mgmt "environment") if ssh_default_sudoer is true. Omission is treated as false

    /bfd/${env}/common/sensitive/user/..../ssh_access: bool
    /bfd/${env}/common/sensitive/user/..../ssh_sudoer: bool

20. Similarly to step #9, there are two options for restricting SSH access in the environment configuration:

    1. Simply set ssh_access to false. Assuming that ssh_default_access was set to false in step #9, this will disable access to this environment entirely
    2. Remove the keys associated with the user. Assuming that the user's corresponding ssh_user and ssh_public_key keys in mgmt were also removed, the user will no longer have access to SSH into this environment

21. Close the file. This will save your changes and re-encrypt the encrypted YAML file for the current environment.

22. 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 #20:

    terraform plan

23. Repeat steps #14 through #22 for each environment that the user should be removed from

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

25. 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

26. Once approved, the changes to each established environment can also be applied:

    1. cd into the base service Terraform module:

       cd ops/terraform/services/base

    2. Switch to the current environment's corresponding workspace:

       terraform workspace select <prod|prod-sbx|test>

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

       terraform apply

    4. Repeat the above steps for each established environment that was changed

27. Once finished, the user's access will be fully updated the next time the Build App AMIs stage is ran in our deployment pipeline.