Keycloak on Dokku.

Intro

Authentication and authorization is the bread and butter business of IT systems and web apps.

Done right they allow you to write applications that integrate with any authentication systems seamlessly. From simple user/password to Google, LDAP and custom SAML systems.

Good authentication systems also allow users to reset their login, reset their passwords, registers and use a second factor.

Keycloak

Keycloak is such an authentication server. It’s battle tested and can be used out of the box. The cool thing is that you can host it yourself and configure it easily to your needs.

I frequently architect and develop apps for larger clients running Keycloak (and similar systems). So for me it was important to have a Keycloak instance for my applications. It’s a great showcase and it allows me to write enterprise grade applications from the start.

Keycloak provides cool stuff such as:

• Authentication, Authorization (Login, Registration etc)
• OpenID connect
• User login via Google, Github and many third party providers
• Custom SAML integration (LDAP etc)

Alternatives to Keycloak

Of course there are alternatives. Many are using SaaS authentication systems these days. Something like Auth0 also provides a good starting point without the need to install anything yourself.

But I wanted to explore Keycloak, so that was not an option for me.

Dokku

I am using Dokku for my projects. It’s like Heroku, but self-managed on your server. It allows me to run my apps with a simple git push dokku on a Debian server. Awesome.

Wouldn’t it be great to also simply install Keycloak via Dokku?

Keycloak on Dokku

There’s an official Keycloak Docker container. Unfortunately that Docker image does not work right away with Dokku. There are also some wrappers out there that allow you to install Keycloak on Dokku. Unfortunately all of them were outdated and did not work. Meh.

Solution? Simple - I created a new one that works for me.

The basic steps to make it work were:

• Disassemble the DATABASE_URL created by the Dokku postgres plugin into variables that can be understood by Keycloak
• Provide an initial admin password to Keycloak
• Tell Keycloak that it is running behind ngnix that does all the SSL termination.

The result is the following script that will be bundled with the official Keycloak Docker container.

Conclusion

If you want to run Keycloak on Dokku then simply head over to https://github.com/raphaelbauer/dokku-keycloak and follow the instructions. It won’t take more than 5 minutes to get it up and running.

Feedback much appreciated!

More

• Docker wrapper to run Keycloak on Dokku: https://github.com/raphaelbauer/dokku-keycloak
• Awesome photo on top by frank mckenna