Keycloak

Keycloak is a single sign-on solution for web apps and RESTful web services. Keycloak aims to simplify security so that it is easy for application developers to secure the apps and services they have deployed in their organization. Security features that developers normally have to write for themselves are provided out of the box and are easily tailored to the individual requirements of your organization. Keycloak provides customizable user interfaces for login, registration, administration, and account management.

Software Included

Creating an App using the Control Panel

Click the Deploy to DigitalOcean button to create a Droplet based on this 1-Click App. If you aren’t logged in, this link will prompt you to log in with your DigitalOcean account.

Creating an App using the API

In addition to creating a Droplet from the Keycloak 1-Click App using the control panel, you can also use the DigitalOcean API. As an example, to create a 4GB Keycloak Droplet in the SFO2 region, you can use the following curl command. You need to either save your API access token) to an environment variable or substitute it in the command below.

curl -X POST -H 'Content-Type: application/json' \
         -H 'Authorization: Bearer '$TOKEN'' -d \
        '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image": "sharklabs-keycloak"}' \
        "https://api.digitalocean.com/v2/droplets"

Getting Started After Deploying Keycloak

After your droplet is created, you can access your Keycloak instance by typing the droplet’s IP address in your browser. Your browser is likely to show a Privacy Error, however, this is completely expected as Keycloak 1-Click uses self-signed certificates. If you get a Privacy Error, click on Advanced and Proceed to...:

After this, you will be greeted by the Keycloak login page:

If you see the Site can’t be reached or Nginx 502 Bad Gateway, give it 2-3 minutes and reload the page.

Retrieve login credentials

To retrieve login credentials, SSH into your Keycloak Droplet 1-Click:

$ ssh root@<your droplet IP>

Now you can read the file with Keycloak passwords by using:

$ cat ~/.digitalocean_passwords

This will return 3 passwords

• KEYCLOAK_ADMIN_PASSWORD: Use this password to log in as an admin user.
• KEYCLOAK_DATABASE_PASSWORD: Password to the database used by Keycloak.
• KEYSTORE_PASSWORD: Password to the certificates keystore.

Now you can log in as an admin user with the KEYCLOAK_ADMIN_PASSWORD you just retrieved!

Configuring Nginx

After you have created your Keycloak droplet, it is highly recommended you configure an Nginx server block file for each site you plan to host. Doing so will make the default configuration the fallback, as intended, and will make it easier to manage changes when hosting multiple sites.

To do so, you’ll need to create two things for each domain: a new directory in /var/www for that domain’s content, and a new server block file in /etc/nginx/sites-available for that domain’s configuration. For a detailed walkthrough, you can follow How to Set Up Nginx Server Blocks.

Adding a domain name

A domain name allows others to access your website with an encrypted connection. If you intend to host a website on your Keycloak Droplet 1-Click.

Keycloak Droplet 1-Click comes with certbot installed, making it easier to enable HTTPS on your 1-Click.

First, ensure your domain points to the new droplet IP. If your DNS is managed by DigitalOcean, it should look like this:

The DNS Host may be the same company you registered the domain with or another entity you designate. To connect your DNS hosting to DigitalOcean, check out this guide.

Once your A record is set up, you should configure nginx to host your new domain properly. Detailed instructions can be found in this article.

After you have configured the domain and nginx, you can run certbot to acquire HTTPS certificates for your droplet:

$ certbot –nginx -d <your domain> -d www.<your domain>

After you answer questions from certbot, your HTTPS setup is finished.

Use your domain in the web browser to access your Keycloak Droplet.

Droplet summary

• UFW firewall allows only SSH (port 22, rate limited), Nginx (ports 443 and 80) and Keycloak (ports 8443 and 9000).
• Keycloak is running under the docker container. To check logs use:

$ docker logs keycloak

• Nginx is configured to redirect requests to Keycloak, acting as a reverse proxy for the application server.
• The message of the day (MOTD) shows the system and database user passwords, which are also saved in /root/.digitalocean_passwords.
• The Keycloak dockerfile can be located at /var/digitalocean/Dockerfile.