Configure Keycloak on Amazon Elastic Kubernetes Service (Amazon EKS) using Terraform

Identity and Access Management (IAM) is a business and security discipline that helps ensure the right individuals have access to the correct resources. Organizations often have several IAM frameworks and business processes for their employees to obtain the resources necessary for them to complete their roles.

Often, these applications have their own custom IAM patterns, leaving development teams with increased overhead. Keycloak is an open source IAM solution that allows organizations to centralize access keys to secure applications, microservices, and APIs. By using Keycloak, organizations can centralize IAM processes and help improve their security posture while relieving their development teams of some of the IAM processes.

In this post, you will learn how to configure Keycloak on Amazon Elastic Kubernetes Service (Amazon EKS) using Terraform. After going through this exercise, you will know how to use Amazon Web Services (AWS) services and open source tools to manage an open source application in AWS.

Solution overview

Terraform is used as infrastructure as code (IaC) to automate the AWS infrastructure provisioning, NGINX Ingress Controller, and Keycloak deployment to Amazon EKS using Helm Charts. The solution includes the following components:

Amazon Virtual Private Cloud (Amazon VPC) with public and private subnets, NAT gateways, and internet gateway
Amazon Aurora MySQL-Compatible Edition
Amazon EKS Cluster provisioning with AWS managed node group, metrics server, and autoscaling
Amazon EKS AWS Load Balancer Controller (ALB) Ingress Controller
Amazon EKS Autoscaler Controller
AWS Certificate Manager (ACM) public certificate provisioning for sample application domain and Keycloak domain
Domain Name System (DNS) record configuration in existing Amazon Route 53 hosted zone
NGINX Ingress Controller deployment with Application Load Balancer provisioning
Keycloak.X deployment to Amazon EKS

This diagram depicts a user accessing the Keycloak application over public internet. It includes the VPC, EKS, and database configurations, as well as the internet and NAT Gateway access patterns:

Accessing Keycloak on the public internet

Prerequisites

To provision the required AWS services, and to deploy Keycloak, you must have the following prerequisites:

A Git client to clone the source code in a repository
An IAM user with Git credentials
An AWS account with local credentials properly configured (typically under ~/.aws/credentials)
The latest version of the AWS Command Line Interface (AWS CLI), which you can learn more about by visiting installing or updating the latest version of the AWS CLI
The latest version of Kubectl, which you can learn more about by visiting Install Tools on Kubernetes
The latest version of Terraform, which you can learn more about by visiting Install Terraform
The latest version of Helm, which you can learn more about by visiting Installing Helm
A bash shell
A public Route 53 hosted zone
An ACM certificate associated with the public Route 53 hosted zone

Keycloak overview

Keycloak is an open source IAM solution that organizations use to manage their applications and services. Enterprises use Keycloak as a centralized authentication system for their various applications, services, and development teams.

By using Keycloak, applications don’t have to manage their own custom login forms, user authentication patterns, or store user information. Keycloak offers organizations the ability to centralize their IAM processes, so that applications and development teams can follow a standardized, common process.

Once users log into Keycloak, they do not have to login again to access different applications. This lets developers work across several applications without repeatedly logging in and out. Additionally, Keycloak offers security teams a centralized tool where teams can verify their applications and services follow best practices.

Keycloak offers many features that are useful in managing modern applications. Among them are an administrative console, user federation with Lightweight Directory Access Protocol (LDAP), and single sign-on (SSO). SSO helps users avoid dealing with login forms.

Keycloak can use an existing LDAP user federation provider to federate users to Keycloak from a directory system like LDAP or Active Directory. Keycloak offers an administrative console where administrators can control the components of the Keycloak server, such as managing users, authorization policies, and overall permissions and sessions.

Finally, for organizations that use social login or identity brokering, users can link their accounts with their identity providers for authentication.

Amazon EKS configuration

The Terraform code is configured with three modules: cluster, cluster-autoscaler, and database. The cluster module contains the networking configuration, such as VPC’s and subnets, the Amazon EKS cluster, and IAM roles and policies. The cluster-autoscaler module configures the Amazon EKS Cluster Autoscaler, a core component of the Kubernetes control plane that makes scheduling and scaling decisions.

Finally, the database module includes the Aurora MySQL-Compatible configurations for Keycloak’s backend database. This project uses Makefile for the deployment steps. Additionally, the project uses a terraform.tfvars file where users populate required information, such as their ACM certificate.

Users deploy Keycloak once the Terraform deployment completes and resources are configured in the AWS account. There are several steps in the Makefile that configure the cluster and Keycloak application. For example, the Makefile configures the local Kube config file, so users can access the Amazon EKS cluster through their local terminal. The kubeconfig file contains details for cluster authentication information for the kubectl CLI (default location) $HOME/.kube/config.

The Kubernetes ConfigMap, which is configured in the Terraform deployment, populates your current IAM role Amazon Resource Name (ARN). Terraform code also configures ExternalDNS, an open source project that facilitates the integration of exposed Kubernetes services and ingresses with Domain Name System (DNS) providers, such as Route 53.

The external DNS configuration provisions a service account, cluster role, cluster role binding, deployment with AWS account, and Route 53 information. The Makefile also configures and deploys manifest/keycloak.yml files. Many attributes of the Keycloak server configuration are set in this manifest file. For example, the username, password, and Route 53 hosted zone are set in this configuration.

Next, deploy the Keycloak application to Amazon EKS.

Deploy Keycloak to Amazon EKS

1. Clone the code repository and change directory into the newly created directory using the following command:

git clone https://github.com/aws-samples/configure-keycloak-on-eks-using-terraform.git

2. Open “terraform/terraform.tfvars” and update the following values:

db_username       = “auroraserverless” # Input Database username
db_password       = “<input_db_password>” # Input Database password
route53_zone_id   = “<input_route53_zone_id>” # Input your public hosted zone Route53 ID
route53_zone_name = “<input_route53_zone_name>” # Input your Route 53 Zone Name
keycloak_username = “demo_user”
keycloak_password = “<input_keycloak_password” # Input a password for ccessing Keycloak Server
cert_arn          = “<input_your_acm_cert_arn” # Input your ACM Cert ARN
database_name     = “keycloakdemo”
environment       = “dev”
cluster_version   = “1.27”

3. Initialize the Terraform modules, and run the following command:

make plan

This will result in a great deal of output ending in the following:

Plan: 91 to add, 0 to change, 0 to destroy.

4. Deploy the AWS infrastructure by running these commands. Pay attention to the “db_hostname” output value, which you will use in the next step.

make apply

This will result in great deal of output ending in the following:

Apply complete! Resources: 105 added, 0 changed, 0 destroyed.

Outputs:

db_hostname = keycloakdemo.cluster-abc123456.us-east-1.rds.amazonaws.com

cert_arn = "arn:aws:acm:us-east-1:01234567890:certificate/1234567ab-1234-1234-1234-123456789av"

5. Open the “terraform/manifest/keycloak.yml” file. Update the “KEYCLOAK_ADMIN_PASSWORD, DB_PASSWORD” with a password of your choosing. Update the “DB_ADDR” with the “db_hostname” Terraform output from the previous step. Under “apiVersion,” update “alb.ingress.kubernetes.io/certificate-arn” with your cert_arn from the previous step. Under “spec,” update “hosts” and “host” using your domain name.

6. Update your Kube config file to point to the newly created cluster, and run the following command:

make update-kube-config

The output should look like the following:

Updated context arn:aws:eks:us-east-1:1234567890:cluster/keycloak-demo in /Users/your_user_name/.kube/config

7. Deploy the AWS infrastructure, and run the following command:

make deploy-keycloak

This will result in a great deal of output ending in the following:

INFO: Deploying Keycloak to EKS.
cd terraform/script && \
sh eks_deploy.sh
service/keycloak created
deployment.apps/keycloak created
ingress.networking.k8s.io/ingress-keycloak created

8. Verify that Keycloak is running.

kubectl get pods -A

The output should look like the following:

default       demo-aws-load-balancer-controller-56786c7678-hxvrs   1/1     Running   0          11m
default       demo-aws-load-balancer-controller-56786c7678-wkjbh   1/1     Running   0          11m
default       external-dns-5bdc87d86f-8cj7g                        1/1     Running   0          3m31s
default       keycloak-86b7fd57c7-7jlcn                            1/1     Running   0          105s
kube-system   aws-cluster-autoscaler-6b684f56d5-trq62              1/1     Running   0          11m
kube-system   aws-node-z5dc9                                       1/1     Running   0          9m46s
kube-system   coredns-7975d6fb9b-5829g                             1/1     Running   0          15m
kube-system   coredns-7975d6fb9b-8v58c                             1/1     Running   0          15m
kube-system   kube-proxy-nhp67                                     1/1     Running   0          9m46s
kube-system   metrics-server-8ff8f88c6-zhknq                       1/1     Running   0          11m

9. Open a browser and navigate to keycloak.<input_your_domain>.com. Select “Administrative Console.” This screenshot depicts the webpage that will appear, titled, “Welcome to Keycloak.” From here, you can navigate to the administrative console, access documentation such as user guides, and more.

Keycloak welcome page

10. Login using your username and password. This screenshot shows a sign-in page requesting a username and password.

Keycloak login screen

11. Finally, you’ll be directed to the Keycloak administrative landing page. This screenshot depicts a webpage that contains details about the master realm.

Keycloak master realm screenshot

Cleanup

To delete the AWS infrastructure you deployed in this walkthrough, run the following command:

make destroy

The command will result in a great deal of output. The final result should look like the following:

Destroy complete! Resources: 91 destroyed.

Conclusion

This post demonstrated how to use AWS services and open source tools to automate the deployment of the open source tool, Keycloak, to AWS. It explained how to use Terraform to deploy [VR14] the infrastructure necessary to run Keycloak on Amazon EKS, as well as verify a successful deployment by logging into the Amazon EKS console.

The resources deployed in this article are for demonstration purposes and users should incorporate additional security controls following AWS best practices before implementing this pattern for their organization.

For more reading, learn more using the resources below: