MoH Keycloak client configuration

This repository holds Keycloak client configuration files for the Ministry of Health Keycloak instance. Developers can open pull requests to change their client configuration.

How to update a client configuration

1. Get permission from the Access Management Team to make pull requests to this repo.
2. Create a pull request with your proposed changes to a client configuration file. Make sure your changes are properly formatted.
3. An automatic process will compare your changes to the current state of Keycloak.
4. A bot will add a comparison report to your pull request.
5. An Access Management Team member will merge your changes into the main branch.
6. An automatic process will apply your changes to the Keycloak instance.

Automation

A GitHub Actions workflow is used to apply the configurations to the Keycloak instance using Terraform.

Overview

⚠ GitHub Actions uses a local Terraform executable, not Terraform Cloud. This diagram has not been updated.

The workflow will:

1. check whether the configuration is formatted properly to demonstrate how you can enforce best practices
2. generate a plan for every pull request
3. apply the configuration when you update the main branch

Detailed description

1. Checkout check outs the current configuration. Uses defines the action/Docker image to run that specific step. The checkout step "uses" GitHub's actions/checkout@v2 action.
2. Setup Terraform retrieves the Terraform CLI used in the GitHub action workflow.
3. Terraform Format checks whether the configuration has been properly formatted. If the configuration isn't properly formatted this step will produce an error. It enforces Terraform best practices by preventing your team from merging unformatted configuration to main. In case of formatting errors, detailed explanation is displayed (steps.fmt.outputs.stdout). This allows your team to review the formatting changes that need to be done directly in the PR instead of viewing the GitHub Actions log.
4. Terraform Init initializes the configuration used in the GitHub action workflow.
5. Terraform Validate validates the configuration used in the GitHub action workflow.
6. Terraform Plan generates a Terraform plan. Notice:
   • This step only runs on pull requests. The PR generates a plan. When the PR is merged, that plan will be applied.
   • This step will continue even when it errors. This allows the next step to display the plan error message even if this step fails.
7. Update Pull Request adds a comment to the pull request with the results of the format, init and plan steps. In addition, it displays the plan output (steps.plan.outputs.stdout). This allows your team to review the results of the plan directly in the PR instead of viewing the GitHub Actions log. This step only runs on pull requests.
8. Terraform Plan Status returns whether a plan was successfully generated or not. This step highlights whenever a plan fails because the "Terraform Plan" step continues on error.
9. Terraform Apply applies the configuration. This step will only run when a commit is pushed to main.

Local set-up (Access Management team only)

In some rare cases you may need to set up Terraform locally. It is easy to do so. Note that this same configuration is used by GitHub Actions, so may refer to its commands and secrets for comparison.

1. Install Terraform (use version identified in https://github.com/bcgov/moh-keycloak-client-configurations/blob/main/.github/workflows/terraform.yml).
2. Set environment variables.
3. Checkout the project.
4. Run terraform init -backend-config="role_arn=$AWS_S3_BACKEND_ROLE_ARN".

Once the above steps are complete, you will be able to run all Terraform commands.

Terraform format

This repository enforces having all configuration formatted in the same manner. To ensure proper formatting run terraform fmt -recursive from the root of moh-keycloak-client-configurations. Terraform will modify the files, so they satisfy the formatting constraints. Environment variables set-up is not necessary to run this command, it can be performed by anyone who has Terraform installed. In case of being unable to install Terraform, formtting issues need to be resolved manually.

Environment variables

Terraform uses these secrets to access its state file stored on AWS.

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_S3_BACKEND_ROLE_ARN
• TF_VAR_dev_client_secret
• TF_VAR_test_client_secret
• TF_VAR_prod_client_secret

The values for the AWS environment variables are stored in the AWS Parameter Store for parameter /octk/service-accounts/s3-admin.

Example:

{
  "access_key_id": "VALUE_OF_AWS_ACCESS_KEY_ID",
  "access_key_secret": "VALUE_OF_AWS_SECRET_ACCESS_KEY",
  "roles": {
    "cey5wq_sandbox_s3_admin": "VALUE_OF_AWS_S3_BACKEND_ROLE_ARN"
  }
}

The values for the TF_VAR_ENV_client_secret environment variables are Keycloak client secrets. To retrieve them, login to the development, test, and production Keycloak Admin Console and lookup their values at moh_applications (realm) > terraform (client) > Credentials (tab).

References

• Terraform Backend Configuration
• Terraform S3 backend
• Terraform Keycloak Provider

Notes for starting from scratch

The Terraform state file containing Keycloak configuration is stored in an S3 bucket on the BCGOV AWS platform. In order for this to work, Terraform requires a service account with the necessary permissions to access the bucket. To fulfill this requirement, a request was submitted on the BCGOV Cloud RocketChat channel. The following is the text of the original request.

May I request a service account to have AmazonS3FullAccess Managed policy in the cey5wq-sandbox environment?

Assuming we create buckets prefixed with the license plate cey5wq, can we have the service account that have enough permissions to control the buckets prefixed with cey5wq? Something like this below?

(My intent is to store Terraform state for our Keycloak instance in a sandbox-environment S3 bucket.)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::cey5wq-*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::cey5wq-*"
    }
  ]
}

Acknowledgements

This README uses some text verbatim and diagrams from Terraform's documentation.