Provided by fme AG
This repo provides IaC that would deploy a keycloak server on AWS as well as scripts to set up rudimentary SAML and OIDC clients for AWS access federation.
The repo has been tested to work with Keycloak 18.0.2, Keycloak 19.0.1, and Keycloak 20.0.1 (which is currently distrubuted as quay.io/keycloak/keycloak:latest
). The latest
tag in user_data/keycloak.sh
can be changed to a fixed version, if later releases will break the compatibility.
- An AWS account and working AWS access key and secret
- bash (if you want to run the scripts, at least)
- Terraform
- jq
- docker (or an alternative tool such as podman). Alternatively, you can install java and run kcadm.sh directly.
- The terraform modules repo cloned to
../terraform-modules
Before the deployment is possible, a few things need to be provided first
- Create a hosted zone that controls a domain or a subdomain. To use keycloak as an OIDC IDP for AWS, a domain and a TLS certificate are needed. Terraform can create the corresponding route53 entry, if a hosted zone ID is provided. These instructions can help with a hosted zone creation.
- Create an export bash file (or export the corresponding variables manually)
cat<<EOF>export.sh
#!/bin/bash
export TF_VAR_hosted_zone_id='YOUR_HOSTED_ZONE_ID'
export TF_VAR_root_dn='YOUR DOMAIN OR SUBDOMAIN THAT IS CONTROLLED BY THE HOSTED ZONE ABOVE'
export TF_VAR_mail='yours@example.com'
export TF_VAR_postgres_password='some password'
export TF_VAR_keycloak_password='another password'
export KC_USER_PASSWORD='yet another password'
EOF
Replace the placeholders with proper values and source the resulting file.
If you feel the need, you can adjust the instance size and other parameters in the .tf files.
source ./export.sh
./rsa.sh
./jar.sh
terraform init
terraform plan -out plan
terraform apply plan
Shortly after the deployment is complete, keycloak should become accessible under https://auth.${TF_VAR_root_dn}
. For instance, if your domain is my.example.com
, then the keycloak address would be https://auth.my.example.com
. A valid Let's encrypt certificate should be acquired automatically and available for this domain. If you do not provide a valid domain controlled by you, the deployment will be incomplete and keycloak will not start properly.
source ./export.sh
./kcsaml.sh
pushd aws-saml
terraform init
terraform plan -out plan
terraform apply plan
./kccommands.sh
- Open the browser (I would recommend Google Chrome or something chromium-based). Press
F12
and go to the network tab. - Go to
https://auth.${TF_VAR_root_dn}/realms/awsfed/protocol/saml/clients/amazon-aws
. Login usingtestuser
and${KC_USER_PASSWORD}
(the value, you set as described above). - You should be redirected to the AWS console of your AWS account with ReadOnlyAccess rights. Of course, you can change the policy to whatever you want in
aws-saml/iam.tf
. - In the network tab of the browser developer tools, you should see the document called
saml
. Copy its value and save it asassertion
(assuming your are still in./aws-saml
) - Run
./saml.sh
. You should be able to assume the first role but not the second, becausetestuser
does not have it assigned. This proves the point that AWS do check SAML assertions for the role you actually try to assume.
popd
(Requires the scripts for SAML (above) to be executed first)
source ./export.sh
./kcoidc.sh
pushd aws-oidc
source ./thumb.sh
terraform init
terraform plan -out plan
terraform apply plan
./oidc.sh
In this case, you can assume the role straight away without anything assigned to testuser
in keycloak. Compare this to the SAML case, where we had to run ./kccommands.sh
that creates a role and role mapping after running terraform.
Got you interested? Read the upcoming blog post to learn how to properly secure OIDC access to AWS.
(Assumes that the scripts from the previous section were executed)
./oidc_protected.sh
popd
In this case, you should be able to access the first but not the second role. This is because testuser
is in the aws_access
but not in the aws_access_exclusive
group (which does not even exist yet).
Creating the group in the Keycloak admin console and assigning it to testuser
fixes this.
Assuming you are in the root folder of the repo,
pushd aws-saml
terraform destroy
popd
pushd aws-oidc
source ./thumb.sh
terraform destroy
popd
source ./export.sh
terraform destroy