Many of you might have already used a service like Auth0 to hand-off user authentication and authorization to a dedicated service. I think this is a sane solution to the ever-growing problem of getting authentication right. Technologies like OAuth and JWT sound great, but they are very easy to get wrong with mistakes that are very hard to discover. Also, implementing authentication again and again is hardly fun. So, Auth0 or Firebase are nice solutions to hit the ground running, but some projects (or budgets for that matter) require self-hosted solutions, like Keycloak.

Keycloak as a free, self-hosted authentication server

As the project describes itself, Keycloak is an "open source identity and access management [tool] for modern applications and services", which allows you to "add authentication to applications and secure services with minimum fuss. No need to deal with storing users or authenticating users. It's all available out of the box. You'll even get advanced features such as User Federation, Identity Brokering and Social Login.".

Why would you want this?

• Save money in the long run. Auth0 starts at 23 USD / month for 1.000 users.
• Building your own solution is hard. Very. And not nearly as good.
• Login + Registration for a new service set up in minutes.
• E-Mail verification is built-in.
• 2FA is built-in.
• Social logins for sites like Facebook, Twitter, LinkedIn, Instagram, GitHub, GitLab – only a few clicks away.
• Bring your own theme!
• Use as a SSO (Single Sign On) solution for multiple services
• Connect to existing LDAP or Active Directory services

If I wanted to build something like this, it would take me months and I still wouldn't know it's safe.

Sounds great? It is. Let's give it a spin, shall we?

Deploy to DigitalOcean App Platform

Recently, DigitalOcean launched the PaaS solution, called DigitalOcean App Platform. Since we want to take the hassle out of authentication, this seems like a perfect fit to deploy our own authentication server.

I assume, that you have basic devop knowledge, including DNS servers, environment variables, databases, docker, and stuff.

1. The container

Luckily, Keycloak provides a container, optimized and ready to go. It's rather new and called 'keycloak-x'. You can read more about it here. And more about it's configuration here.

2. Your repository

DigitalOcean App Platform deploys your apps right from their respective git repositories. You can provide a Dockerfile or use the readily available environments provided by DO. Since we already have a container, you can go ahead and create an empty repository for this project on GitHub or GitLab. All you need in this repository is a simple Dockerfile:

FROM quay.io/keycloak/keycloak-x

3. Set up a database

You can configure a development database in step 4, create a new database in an existing database server, or create a new database server now.

Sign into your DO account and create a new database server. We will use MySQL in this example. Configure your cluster as you like. We're going with the smallest configuration. Once your database server is deployed, add a new database called keycloak and a new user, also called keycloak. Copy all credentials for the next step.

4. Set up your DigitalOcean App

Hit the big green 'Create' button and start creating a new 'app'. Connect your GitHub or GitLab account if you haven't already. Select the repository below and click 'next'. Choose a name and region and proceed to the next step. Here, we have a few settings to make. DigitalOcean should have detected the Dockerfile. We want to deploy it as a Web Service with the following environment variables:

KEYCLOAK_ADMIN=yourusername
DB_VENDOR=mysql
DB_ADDR=
DB_PORT=
DB_DATABASE=keycloak
DB_USER=keycloak
DB_PASSWORD=
KC_PROXY_MODE=edge
KC_METRICS_ENABLED=true
KC_HTTP_ENABLED=true
KC_HOSTNAME_FRONTEND_URL=https://auth.example.com/
KC_HOSTNAME_ADMIN_URL=https://auth.example.com/

Of course, make sure to provide the correct details for your database connection and set your own keycloak username and a strong password. Note that we're disabling https here since the SSL connection will be terminated by DO. Also, make sure to add a trailing / to the hostname urls!

Port is 8080 and health checks should work fine with TCP.
(Actually, although health check urls are enabled using KC_METRICS_ENABLED, I didn't manage to get HTTP health checks working yet. So if you see something that I didn't, please leave a comment.)

Go ahead and deploy!

5. Configure your very own keycloak server

By now, your keycloak instance should be up and running. I would recommend adding another domain in the settings of your DigitalOcean app. You don't have to, though. Just make sure KC_HOSTNAME_FRONTEND_URL and KC_HOSTNAME_ADMIN_URL match your generated or custom domain and your DNS servers are configured accordingly.

You can access your installation under the assigned or your custom domain. Simply log in with your admin credentials.

If you need some help getting started with keycloak, I can recommend this video: https://www.youtube.com/watch?v=duawSV69LDI

Also, I had a problem where I couldn't access the login screen of the realm I created in keycloak. All I ever got was an alert that keycloak could not be initialized and a 403. It turned out eventually, that I needed to set the Web Origins setting of my client to a wildcard: * to allow access from any origin. But that was simply a beginner's mistake.

Hope you had an easy time following along. Leave a comment below and tell me how it went and what you're planning to do with it!