The objective of this guide is to deploy Keycloak to EC2 AWS Ubuntu machine.
Mostly this Gist is a distillation of the Keycloak Server Installation guide for a specific use case: to spin up a quick and dirty Keycloak instance for testing and experimenting.
- Spin up and configure a Ubuntu AMI
- Install and configure Keycloak with an SSL cert
Use the AWS console to create a new EC2 instance. We're only testing Keycloak out so a t2.micro is good. Assign it a security group with inbound ports 22 (SSL), 8080 (TCP) and 8443 (TCP) open. Restrict these to your current IP.
22 SSH
8080 TCP
8443 TCP
Keycloak has quite straightforward system requirements. You pretty much just need to update to Java 8.
SSH into the instance and run:
sudo apt-add-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer
This will get the latest Java8 and install it. To check you've got things installed right run java -version and check it's saying 1.8.<something>.
/usr/local/bin is for normal user programs not managed by the distribution package manager, e.g. locally compiled packages.
You should not install them into /usr/bin because future distribution upgrades may modify or delete them without warning.
Download and extract the Keycloak tarball.
curl –O https://downloads.jboss.org/keycloak/<VERSION>/keycloak-<VERSION>.tar.gz
tar -zxvf keycloak-<VERSION>.tar.gz
This should have extracted everything into a keycloak-<VERSION> directory.
Get hold of your AWS instance's private (internal) IP address. We need to bind Keycloak to that in order to access it from the outside world.
Using the private instance IP you can start keycloak with the following command:
./bin/standalone.sh -b <INSTANCE PRIVATE IP>
Behold! Keycloak should start. You will see lots of output, and with any luck none of it will be red. Eventually it will log a message containing something like:
Keycloak 2.3.0.Final (WildFly Core 2.0.10.Final) started in 20686ms
Binding the IP is a bit of a gotcha because it's easy to forget to do and then you're left scratching your head, so if you're going to be starting Keycloak often you might like to configure the port binding in config.
Now, because we bound Keycloak to the instance private IP, we can SSH tunnel in to the admin interface using the instance's public DNS (or public IP).
On your local machine, in a new terminal instance:
ssh -i /path/to-your-aws.pem -L 8080:<instance public DNS/IP>:8080 <instance public DNS/IP>
In a browser visit localhost:8080. You should be greeted by Keycloak. You can log in to the admin interface and set up a user here, or...
If you can't be bothered to tunnel in to set the user up you can run Keycloak's add-user.sh from the instance's CLI.
./bin/add-user-keycloak.sh -r master -u <username> -p <password>
(See: Keycloak server admin guide)
By default Keycloak will only accept connections over SSL (with the exception of localhost). You can set Keycloak to operate in the open over HTTP but makes me uncomfortable if there's going to be secure-type-stuff going through it, so I recommend you do bother to set up certs.
The version of Ubuntu you're running will affect the method you use to obtain a cert from LetsEncrypt. Go to the Certbot website and locate the "none of the above" instructions for your OS version. Follow them.
Now you've got a cert, follow the instructions Keycloak give for creating a Java Key Store (.jks) and configuring Keycloak to use it.
All being well you can now start Keycloak and visit it over HTTPS using your instance's public DNS. It will be on port 8443 because that's how Keycloak rolls.
https://ec2-<something something>.<some location>.compute.amazonaws.com:8443