Skip to content

guardianproject-ops/terraform-aws-ecs-keycloak

BranchesTags

Repository files navigation

terraform-aws-ecs-keycloak

The Guardian

Terraform module for deploying Keycloak to AWS ECS w/ Fargate

It's 100% Open Source and licensed under the GNU General Public License.

Introduction

Goals of this module

  • Run a stable and reliable keycloak that doesn't need to scale beyond 100 users
  • Trading cost for low effort on going maintenance
    • We want this stack to run without having to worry about OS patching or other issues ec2 instance related issues
    • We don't mind spending 20-40% more per month on fixed infra costs to achieve this
  • Security with escape hatches
    • This keycloak will be our IdP or wide including acting as the IdP for AWS and Gitlab, where keycloak itself is hosted
    • So there must be documented escape hatches and break-glass procedures, these are documented in our internal docs.

Architecture Decisions

  • Run on ECS

    • Pros: only need to worry about containers, no need to manage instances or disks.
    • Cons: bigger up-front dev time to develop this stack, wonky restrictions compared to normally running on an instance

  • ECS containers are in public subnets, but locked down

    • We do this to avoid NAT Gateway charges. Security groups are tuned carefully. Bonus benefit is tailscale is faster as it doesn't use DERP.

  • Keycloak behind ALB with self signed certs

    • ALB uses an ACM cert, keycloak exposes its HTTPS using a self-signed (generated here in terraform)
    • As per AWS' ALB docs:

    The load balancer establishes TLS connections with the targets using certificates that you install on the targets. The load balancer does not validate these certificates. Therefore, you can use self-signed certificates or certificates that have expired. Because the load balancer, and its targets are in a virtual private cloud (VPC), traffic between the load balancer and the targets is authenticated at the packet level, so it is not at risk of man-in-the-middle attacks or spoofing even if the certificates on the targets are not valid. Traffic that leaves AWS will not have these same protections, and additional steps may be needed to secure traffic further.

    • This lets us tick the box of full transit encryption

  • Keycloak admin and management API is not exposed to the public, but only over tailscale

    • This means to login and edit Realms, you must access Keycloak over tailscale
    • What happens when tailscale is down or tailscale+keycloak auth is broken? Refer to our documented break-glass procedures (TL;DR: break glass on AWS account, edit ALB target group to remove path

Some implementation notes

  • Tailscalesd supports AWS SSM storage of state but multiple bugs make this not useable in the container image

  • The tailscale auth-key is stored in AWS Secrets Manager, we use our lambda that rotates auth keys to rotate the auth key regularly and bypass expiry. The auth-key (and the OIDC creds that power the lambda) are locked down such that all nodes that use the auth key must have the given tags.

  • We use two long-running services: keycloak, and tailscale. We do this because it lets us horizontally scale keycloak with more container instances, while keeping a single internal-ingress.

  • tailscale runs a in a single container and provides an internal tailnet reverse proxy to the keycloak upstream

Usage

IMPORTANT: We do not pin modules to versions in our examples because of the difficulty of keeping the versions in the documentation in sync with the latest released versions. We highly recommend that in your code you pin the version to the exact version you are using so that your infrastructure remains stable, and update versions in a systematic way so that they do not catch you by surprise.

Also, because of a bug in the Terraform registry (hashicorp/terraform#21417), the registry shows many of our inputs as required when in fact they are optional. The table below correctly indicates which inputs are required.

For a example usage, please see examples/simple

When deploying for the first time, the tailscale ingress will not be able to connect to the the keycloak service via Service Connect, because the keycloak service is created after the the tailscale ingress service. This is a limitation of AWS Service Connect. The workaround is to force a redeployment of the tailcscale ingress service after the keycloak service comes online.

Requirements

Name Version
terraform >= 1.3
aws >= 5.0.0, < 6.0.0
random >= 3.6.3
tls >= 4.0.6

Providers

Name Version
aws >= 5.0.0, < 6.0.0
random >= 3.6.3
tls >= 4.0.6

Modules

Name Source Version
alb cloudposse/alb/aws 2.2.0
ecs_cluster cloudposse/ecs-cluster/aws 0.9.0
keycloak guardianproject-ops/ecs-web-app/aws 0.0.1
keycloak_def cloudposse/ecs-container-definition/aws 0.61.1
kms_key cloudposse/kms-key/aws 0.12.2
label_alb cloudposse/label/null 0.25.0
label_keycloak cloudposse/label/null 0.25.0
label_log_group_keycloak cloudposse/label/null 0.25.0
label_log_group_postgres_init cloudposse/label/null 0.25.0
label_log_group_secrets_init cloudposse/label/null 0.25.0
label_ssm_params cloudposse/label/null 0.25.0
label_tailscale cloudposse/label/null 0.25.0
postgres_init_sidecar cloudposse/ecs-container-definition/aws 0.61.1
secrets_init_sidecar cloudposse/ecs-container-definition/aws 0.61.1
service_tailscale guardianproject-ops/ecs-service-tailscale/aws 0.0.1
this cloudposse/label/null 0.25.0

Resources

Name Type
aws_cloudwatch_log_group.keycloak resource
aws_cloudwatch_log_group.postgres_init resource
aws_cloudwatch_log_group.secrets_init resource
aws_iam_policy.keycloak_exec resource
aws_iam_policy.keycloak_task resource
aws_iam_role_policy_attachment.keycloak_exec resource
aws_iam_role_policy_attachment.keycloak_task resource
aws_lb_listener_rule.redirect_http_to_https resource
aws_lb_listener_rule.redirect_keycloak_root resource
aws_s3_bucket.keycloak_clustering resource
aws_s3_bucket_public_access_block.keycloak_clustering resource
aws_security_group.alb resource
aws_security_group.keycloak resource
aws_service_discovery_http_namespace.this resource
aws_ssm_parameter.keycloak_password resource
aws_ssm_parameter.keycloak_tls_cert resource
aws_ssm_parameter.keycloak_tls_key resource
aws_vpc_security_group_egress_rule.alb_egress_all resource
aws_vpc_security_group_egress_rule.keycloak_egress_all resource
aws_vpc_security_group_ingress_rule.alb_http resource
aws_vpc_security_group_ingress_rule.alb_https resource
aws_vpc_security_group_ingress_rule.keycloak_cluster resource
aws_vpc_security_group_ingress_rule.keycloak_http resource
aws_vpc_security_group_ingress_rule.keycloak_management resource
aws_vpc_security_group_ingress_rule.keycloak_tailscale_management resource
aws_vpc_security_group_ingress_rule.keycloak_tailscale_web resource
random_password.keycloak_password resource
tls_private_key.keycloak resource
tls_self_signed_cert.keycloak resource
aws_caller_identity.this data source
aws_iam_policy_document.keycloak_exec data source
aws_iam_policy_document.keycloak_task data source
aws_iam_policy_document.keycloak_task_rds_iam data source
aws_iam_policy_document.keycloak_task_s3_cluster data source
aws_iam_policy_document.keycloak_task_secrets data source
aws_region.this data source

Inputs

Name Description Type Default Required
additional_tag_map Additional key-value pairs to add to each map in tags_as_list_of_maps. Not added to tags or id.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.		 map(string) {} no
alarms_sns_topics_arns A list of SNS topic arns that will be the actions for cloudwatch alarms list(string) [] no
attributes ID element. Additional attributes (e.g. workers or cluster) to add to id,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by the delimiter
and treated as a single ID element.		 list(string) [] no
context Single object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables as null to use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.		 any 
{
  "additional_tag_map": {},
  "attributes": [],
  "delimiter": null,
  "descriptor_formats": {},
  "enabled": true,
  "environment": null,
  "id_length_limit": null,
  "label_key_case": null,
  "label_order": [],
  "label_value_case": null,
  "labels_as_tags": [
    "unset"
  ],
  "name": null,
  "namespace": null,
  "regex_replace_chars": null,
  "stage": null,
  "tags": {},
  "tenant": null
}
 no
db_keycloak_host The postgresql host for keycloak string n/a yes
db_keycloak_name The postgresql db name for keycloak string "keycloak" no
db_keycloak_password The postgresql password for keycloak, when not using IAM authentication string null no
db_keycloak_port The postgresql port number for keycloak number 5432 no
db_keycloak_user The password for the keycloak account on the postgres instance string "keycloak" no
deletion_protection_enabled Whether or not to enable deletion protection on things that support it bool true no
delimiter Delimiter to be used between ID elements.
Defaults to - (hyphen). Set to "" to use no delimiter at all.		 string null no
descriptor_formats Describe additional descriptors to be output in the descriptors output map.
Map of maps. Keys are names of descriptors. Values are maps of the form
{<br/> format = string<br/> labels = list(string)<br/>}
(Type is any so the map values can later be enhanced to provide additional options.)
format is a Terraform format string to be passed to the format() function.
labels is a list of labels, in order, to pass to format() function.
Label values will be normalized before being passed to format() so they will be
identical to how they appear in id.
Default is {} (descriptors output will be empty).		 any {} no
enabled Set to false to prevent the module from creating any resources bool null no
environment ID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT' string null no
exec_enabled Specifies whether to enable Amazon ECS Exec for the tasks within the service bool false no
id_length_limit Limit id to this many characters (minimum 6).
Set to 0 for unlimited length.
Set to null for keep the existing setting, which defaults to 0.
Does not affect id_full.		 number null no
java_opts_extra An optional list of arguments to add to JAVA_OPTS list(string) [] no
jvm_heap_max Maximum JVM heap size for Keycloak in MB. The default is 75% of the task_memory number null no
jvm_heap_min Minimum JVM heap size for Keycloak in MB number 512 no
jvm_meta_max Maximum JVM meta space size for Keycloak in MB. number 256 no
jvm_meta_min Minimum JVM meta space size for Keycloak in MB" number 128 no
keycloak_acm_certificate_arn The arn for the ACM certificate used to provide TLS for your keycloak instance string n/a yes
keycloak_admin_subdomain If you want foobar.$tailscale-domain.ts.net to be how you access keycloak admin, then set this variable to "foobar". By default the value is derived from context. string null no
keycloak_admin_username The username for the temporary superuser used to bootstrap the instance string "admin" no
keycloak_container_image The fully qualified container image for keycloak. string "registry.gitlab.com/guardianproject-ops/docker-keycloak:26.0" no
keycloak_node_count The number of keycloak containers to run in clustering mode number 1 no
kms_key_arn The kms key ARN used for various purposes throughout the deployment, if not provided a kms key will be created. This is difficult to change later. string null no
label_key_case Controls the letter case of the tags keys (label names) for tags generated by this module.
Does not affect keys of tags passed in via the tags input.
Possible values: lower, title, upper.
Default value: title.		 string null no
label_order The order in which the labels (ID elements) appear in the id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.		 list(string) null no
label_value_case Controls the letter case of ID elements (labels) as included in id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via the tags input.
Possible values: lower, title, upper and none (no transformation).
Set this to title and set delimiter to "" to yield Pascal Case IDs.
Default value: lower.		 string null no
labels_as_tags Set of labels (ID elements) to include as tags in the tags output.
Default is to include all labels.
Tags with empty values will not be included in the tags output.
Set to [] to suppress all generated tags.
Notes:
The value of the name tag, if included, will be the id, not the name.
Unlike other null-label inputs, the initial setting of labels_as_tags cannot be
changed in later chained modules. Attempts to change it will be silently ignored.		 set(string) 
[
  "default"
]
 no
log_group_retention_in_days The number in days that cloudwatch logs will be retained. number 30 no
name ID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as a tag.
The "name" tag is set to the full id string. There is no tag with the value of the name input.		 string null no
namespace ID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique string null no
port_keycloak_cluster The port number used for Keycloak cluster communication number 7800 no
port_keycloak_management The port number for Keycloak management interface number 9000 no
port_keycloak_web The port number for Keycloak web interface number 8443 no
private_subnet_ids The ids for the private subnets that EFS will be deployed into list(string) n/a yes
public_subnet_cidrs The cidr blocks for the public subnets that ECS will be deployed into list(string) n/a yes
public_subnet_ids The ids for the public subnets that ECS will be deployed into list(string) n/a yes
rds_iam_auth_enabled Whether or not IAM authentication to an RDS instance will be used. bool true no
rds_init_keycloak_db If true then the postgresql database for keycloak will be initialized using the RDS master credentials bool true no
rds_master_user_secret_arn If true then the postgresql database for keycloak will be initialized using the RDS master credentials string null no
rds_master_username The username of the RDS master user string "" no
rds_resource_id The RDS resource id , used when rds iam auth is enabled string null no
redirect_keycloak_root When a users visits the root path of the keycloak instance, they will be redirected to this URL. This is useful for redirecting to a realm's login page. If null, no redirect will be performed. 
object({
    host     = string
    path     = string
    port     = optional(number, 443)
    protocol = optional(string, "https")
    query    = optional(string)
  })
 null no
regex_replace_chars Terraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set, "/[^a-zA-Z0-9-]/" is used to remove all characters other than hyphens, letters and digits.		 string null no
stage ID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release' string null no
tags Additional tags (e.g. {'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.		 map(string) {} no
tailscale_client_id The OIDC client id for tailscale that has permissions to create auth keys with the tailscale_tags_keycloak tags string n/a yes
tailscale_client_secret The OIDC client secret paired with tailscale_client_id string n/a yes
tailscale_container_image The fully qualified container image for tailscale. string "ghcr.io/tailscale/tailscale:stable" no
tailscale_tags_keycloak The list of tags that will be assigned to tailscale node created by this stack. list(string) n/a yes
tailscale_tailnet description = The tailnet domain (or "organization's domain") for your tailscale tailnet, this s found under Settings > General > Organization string n/a yes
task_cpu The number of CPU units used by the task. If unspecified, it will default to container_cpu. If using FARGATE launch type task_cpu must match supported memory values (https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_size) number n/a yes
task_memory The amount of memory (in MiB) used by the task. If unspecified, it will default to container_memory. If using Fargate launch type task_memory must match supported cpu value (https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_size) number n/a yes
tenant ID element _(Rarely used, not included by default)_. A customer identifier, indicating who this instance of a resource is for string null no
vpc_id The VPC id ECS will be deployed into string n/a yes

Outputs

Name Description
alb n/a
cloudwatch_log_group_arn_keycloak Cloudwatch log group ARN for keycloak
cloudwatch_log_group_arn_tailscale Cloudwatch log group ARN for tailscale
cloudwatch_log_group_keycloak All outputs from aws_cloudwatch_log_group.keycloak
cloudwatch_log_group_name_keycloak Cloudwatch log group name for keycloak
cloudwatch_log_group_name_tailscale Cloudwatch log group name for tailscale
cloudwatch_log_group_tailscale All outputs from aws_cloudwatch_log_group.tailscale
keycloak_password n/a
kms_key_arn The KMS Key ARN used for this deployment
secrets_manager_secret_authkey_arn n/a
secrets_manager_secret_authkey_id n/a

Help

Got a question? We got answers.

File a GitLab issue, send us an email or join our Matrix Community.

Matrix Community

Matrix badge

Join our Open Source Community on Matrix. It's FREE for everyone! This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build on our open source code.

Contributing

Bug Reports & Feature Requests

Please use the issue tracker to report any bugs or file feature requests.

Developing

If you are interested in being a contributor and want to get involved in developing this project or help out with our other projects, we would love to hear from you! Shoot us an email.

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

  1. Fork the repo on GitLab
  2. Clone the project to your own machine
  3. Commit changes to your own branch
  4. Push your work back up to your fork
  5. Submit a Pull Request so that we can review your changes

NOTE: Be sure to merge the latest changes from "upstream" before making a pull request!

Copyright

Copyright © 2021-2025 The Guardian Project

License

License: GPL v3

GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Trademarks

All other trademarks referenced herein are the property of their respective owners.

About

This project is maintained by The Guardian Project.

The Guardian Project

We're a collective of designers, developers, and ops folk focused on useable privacy and security with a focus on digital human rights and humanitarian projects.

Everything we do is 100% FOSS.

Follow us on Mastodon or twitter, apply for a job, or partner with us.

We offer paid support on all of our projects.

Check out our other DevOps projects or our entire other set of projects related to privacy and security related software, or hire us to get support with using our projects.

Contributors

Abel Luck
Abel Luck

About

Terraform module for deploying Keycloak to AWS ECS w/ Fargate (Mirror of https://gitlab.com/guardianproject-ops/terraform-aws-ecs-keycloak)

Resources

Readme

License

GPL-3.0 license
Activity
Custom properties

Stars

0 stars

Watchers

3 watching

Forks

0 forks
Report repository

Releases

4 tags

Packages

 
 
 

Contributors

Languages