Keycloak SSO with Docker Compose and Nginx

https://du.nkel.dev/blog/2024-02-10_keycloak-docker-compose-nginx/

by Helmut10001 • 2 years ago

222 108 2 years ago

du.nkel.dev

andix• 2 years ago

Keycloak is great but can be quite confusing for starters. It has a lot of features and not the best documentation. I recently tried Zitadel and found it much easier to use. It's a bit harder to self-host though because it can't run on an embedded database.

mffap3• 2 years ago

That's true it requires its own db. Way forward will be postgres as db, which makes it hopefully easier to deploy alongside other tools.

KronisLV• 2 years ago

I did something similar, though picked Apache with mod_auth_openidc, which is a certified Relying Party implementation: https://github.com/OpenIDC/mod_auth_openidc

In other words, I can protect arbitrary applications through my reverse proxy and require either certain claims/roles, or simplify auth to the point where my downstream app/API will just receive a bunch of headers like OIDC_CLAIM_sub, OIDC_CLAIM_name, OIDC_CLAIM_email through the internal network, not making me bother with configuring OIDC libraries for all of my APIs and configure them in each stack that I might use, but rather contain all of that complexity in the reverse proxy. Handling headers in pretty much every stack is trivial, be it something with .NET, Java, Node, Python and so on...

Basically:

  user <==> Apache (with mod_auth_openidc) <==> API (with OIDC_ headers, if logged in and authorized)
                                        OR <==> Keycloak (for logging in/registration, followed by redirect)

Apache probably isn't the ideal tool for this, but was definitely the easiest to setup and also has mod_md nowadays, making renewing SSL certs (with HTTP-01, at least) closer to how Caddy might do it, I don't even need certbot: https://httpd.apache.org/docs/trunk/mod/mod_md.html

Now, right now I'm moving away from storing groups in the Keycloak DB because it's actually easier to do that in the app DB and only allow Keycloak to reason about who users are, not what they can do (since interacting with Keycloak's API to manage users is cumbersome), especially when I want custom permissions: like users being assigned to companies, but also having specific permissions for each of those companies, your typical granular system.

Personally, I'd definitely say that OIDC feels overcomplicated to work with, so I'm glad that I discovered something like this. There's a whole list of other Relying Party implementations, but nobody really seems to be talking about them: https://openid.net/developers/certified-openid-connect-imple...

Also, in regards to Keycloak in particular, most likely you really want to build the "optimized" image, because otherwise the startup times will be annoyingly long: https://www.keycloak.org/server/containers (like the article already points out, but that was a pain point until I got it over with)

Oh, and Keycloak is known to be a bit odd in how it sometimes works behind a reverse proxy, I actually needed to put this in the configuration because otherwise connections would sometimes break:

  SetEnv proxy-initial-not-pooled 1
  SetEnv proxy-nokeepalive 1

victor106• 2 years ago

This is interesting.

Thanks for sharing.

mooreds11• 2 years ago

Now, right now I'm moving away from storing groups in the Keycloak DB because it's actually easier to do that in the app DB and only allow Keycloak to reason about who users are, not what they can do (since interacting with Keycloak's API to manage users is cumbersome), especially when I want custom permissions: like users being assigned to companies, but also having specific permissions for each of those companies, your typical granular system.

Have you thought about extracting your authorization to a separate server? It might be overkill if you only have one application, but I've seen demos/had conversations with the folks at cerbos and permit, which both offer open source authorization as a service. That way your user authentication is done by Keycloak, your authorization is done by cerbos/permit/etc, and your application only is responsible for application data/functionality.

trollied• 2 years ago

Love keycloak. What I would do differently though is run it on a host (or in a k8s pod) & have it serving via http to localhost, then use cloudflared to tunnel & present it as https. Saves messing around with certificates etc, it's all automatic.

J_tt2• 2 years ago

My go to is always this instead:

https://github.com/lucaslorentz/caddy-docker-proxy

Single label to a docker container and with correct DNS you’ll have an automatically managed certificate right away.

Helmut100013• 2 years ago

I had this discussion before and thought long about using Caddy, but then decided for nginx, directly on the host, basically following this reasoning [1].

My main motivation is that there is just more information available for nginx due to its wider use. And when you need to customize Caddy due to different requirements by services, you end up with the same or worse complexity compared to an nginx .conf. Nginx is just very robust and the configuration is not so hard to get used to.

[1] https://nickjanetakis.com/blog/why-i-prefer-running-nginx-on...

mnahkies• 2 years ago

If nothing else, that posts mention of https://www.keycloakify.dev/ is very handy - looks like a great alternative to the standard approach!

mooreds11• 2 years ago

Ooh, thanks for that. I work for a competitor and we're reworking our theming and this seems like a great project to review and model the rework after.

TN1ck• 2 years ago

It is a great project. I’m using it since two years and can only say good things. The maintainer is very responsive and most recently a change was made to both keycloak and keycloakify to future proof its approach to theming.

Currently it officially supports only apps made with create-react-app, but there is a vite branch in development and personally we use it with vite since a while.

rjzzleep• 2 years ago

I've been eyeing authentik[1] and authelia[2].

Authelia looks really good to me, but the fact that keycloak has connectors for angular and you need to setup oidc angular plugins with authelia for example made me a little bit wary. But I guess having a config for Keycloak makes it's easier to get started.

[1] https://goauthentik.io/

[2] https://www.authelia.com/

c0wb0yc0d3r2• 2 years ago

For anyone, considering authentik, I want to warn you by saying "here be dragons."

To start, I have protected 10+ services at any given time. Both in docker and k8s. Unless you enjoy configuring protection for each service independently, you'll have a bad time in authentik.

Authentik suffers from a debilitating bug[0] where when using a single config to protect all services on subdomains (i.e. app1.example.com, app2.example.com, etc.) your users will be randomly redirected to a different service when reauthenticating after the session expires.

[0] https://github.com/goauthentik/authentik/issues/6886

BeryJu4• 2 years ago

Hey, authentik CTO here!

We’ll be addressing the bug in the release after the next one (march-April)

risson• 2 years ago

Authentik dev here, AMA

slenk• 2 years ago

I am trying to make the same decision right now. Authentik looked better to me but that bug mentioned in another reply sounds bad

kodama-lens• 2 years ago

Authentik has completely messed up their implementation of the oauth client credentials grant. It is not fixable without breaking changes and does not work with many tools using the cc grant.

After seeing this they were completely off the table for me.

https://github.com/goauthentik/authentik/issues/6139

BeryJu4• 2 years ago

authentik CTO here; we’ll fix this in the next release (match-april), it should be possible in a non backwards incompatible way using the suggestion in this comment https://github.com/goauthentik/authentik/issues/6139#issueco... (which does call that solution a hack but I wouldn’t necessarily agree)

BeryJu4• 2 years ago

See here for the fix, which both implements the workaround suggested in the issue and also a much more standard-compliant method: https://github.com/goauthentik/authentik/pull/8471

james_d_elliott5• 2 years ago

One of the Authelia principle maintainers here. If there's anything we can do to help with the configuration of Angular we'd be more than happy to via the GitHub discussions.

c-hendricks3• 2 years ago

I recently went down this road for my home lab and went with Authelia

Keycloak works, but it's a behemoth and still needs further services to work with traefik forward auth.

Authelia works great, you don't get a UI to edit users, and it's not a two-way sync between a backing LDAP server, but the fact that it can be configured with a static file + environment variables makes it a great fit for a lot of cases. If you're just looking to add auth to some services, and SSO to those that can work with it, I'd suggest starting with Authelia.

ffsm82• 2 years ago

I [...] went with Authelia

Great choice!

keycloak [...]'s a behemoth

Really? It prefers a database, sure, but you can also store on disk. And you can also configure the main user with env variables.

It starts within <3s on my toy server since they refractored it a few years ago and uses less then 100mb ram (again, toy server, not many users etc)

Idk, calling that a behemoth is kinda a stretch at that point...?

The thing that annoys me about keycloak is how they decided to ship it. I really don't want to maintain a CI Pipeline to deploy it .. but you're kinda forced to with how they've designed their docker image. Not an issue for enterprise as they're gonna be doing that anyway, but annoying for home servers

c-hendricks3• 2 years ago

Behemoth may be a bit of a stretch, but the container is 20x the size of authelia, it's minimum recommendations are 512mb ram, and 1g of disk space. Compared to Authelia, which is using 30mb of ram and 500k disk space, yeah it's big.

Not to mention, only the admin user being configurable via environment variables isn't enough. With Authelia, I can share my homelab setup and with a couple of environment variable changes, people can have SSO integrated. There's no need to write guides or grab screenshots to help them get set up.

raziel2p2• 2 years ago

have you looked at the codebase? it's been a while but I was implementing Keycloak a few years ago and it was shocking how big the codebase is and how difficult it is to change things to add what felt like basic functionality. making plugins didn't seem like a viable option either.

oh not to mention the statefulnes of it, it was almost impossible to destroy and re create an instance from scratch without a bunch of manual point and click via the UI.

bvrmn• 2 years ago

It would be great to know how you start Keycloak. In our CI it takes 40s-1m to start and consumes 500Mb. We use default docker image.

mooreds11• 2 years ago

Disclosure: I work for FusionAuth.

If you are looking for SSO + easy configuration + an admin UI (which admittedly has a mid 2000s UX look and feel), you should check out FusionAuth. It's free to download and run yourself[0], docker friendly[1], has a variety of configuration choices[2] (including terraform[3] to manage your OIDC/other settings).

Worth noting that it is free to use, but not open source[4].

0: https://fusionauth.io/download

1: https://fusionauth.io/docs/get-started/download-and-install/...

2: https://fusionauth.io/docs/operate/deploy/configuration-mana...

3: https://fusionauth.io/docs/operate/deploy/terraform

4: https://fusionauth.io/license-faq#28

NeckBeardPrince• 2 years ago

So if you self-host you still have to pay to have 2FA?

apitman8• 2 years ago

Genuinely curious, how do you plan to compete with Ory and Zitadel in this space without being open source?

mmcnl3• 2 years ago

How do I integrate this with a reverse proxy like Caddy and their forward_auth directive? I want to secure my apps on the proxy layer, not the app layer.

natrys2• 2 years ago

I also went down this road recently. Personally I had gone with caddy-security[1] which is simply a plugin for Caddy.

[1] https://github.com/greenpau/caddy-security

jallbrit• 2 years ago

I also went down this road recently, and discovered caddy-security, but I have security concerns [0]. Software always has vulnerabilities, but this was enough to scare me off. Something like keycloak or authentia seems more tested and secure.

[0] https://blog.trailofbits.com/2023/09/18/security-flaws-in-an...

BeryJu4• 2 years ago

Authelia has a very unique advantage of its small footprint, which is something that neither Keycloak nor authentik (which I work for as a disclaimer) can really fit into. It’s a very good usecase for a homelab environment and if you don’t need/want features of the “bigger” solutions!

mmcnl3• 2 years ago

I have Authelia running for 2+ years already. I configured it with LDAP using "LLDAP" [0], a lightweight LDAP implementation. I then use Caddy as a reverse proxy and integrate it [1] with Authelia. This works great. I have solid 2FA for all my services and I feel my self-hosted applications are secure enough to be accessed without VPN. My only concern is that Authelia hasn't had a new release for more than a year, which raises security concerns.

[0] https://github.com/lldap/lldap

[1] https://www.authelia.com/integration/proxies/caddy/

ciceryadam2• 2 years ago

Newest arch package is just over 4 months old - Last Updated: 2023-10-09 03:25 (UTC): https://aur.archlinux.org/packages/authelia

c-hendricks3• 2 years ago

My only concern is that Authelia hasn't had a new release for more than a year, which raises security concerns.

I'm a bit concerned about that too. When setting it up, I found a lot of their docs on github mentioned they have `template` and `expand-env` "configuration filters", then it took me entirely too long to realize that while the 4.38 pre-release notes, posted in January 2023, say it's "just around the corner", it's still being worked on.

Having said that, there still seems to be somewhat active development. It may just be one person at this point.

https://hub.docker.com/layers/authelia/authelia/v4.38.0-beta...

https://github.com/authelia/authelia/commits/v4.38.0-beta3/

james_d_elliott5• 2 years ago

Hey one of the Authelia developers here. We're very actively working on a very large release (it's just going through the peer review process and it should be good to go) and we currently have a pre-release for users to dive into.

I can understand the security concerns but we are regularly taking measures to ensure no zero-day vulnerabilities exist, there are no known vulnerabilities with Authelia at the present time either directly or via the code-paths of dependencies we actually use.

rendaw• 2 years ago

Tangential, but are there any alternatives to LDAP today? I googled around and found nothing. Simpler schema, JSON, http, etc. I can't believe nobody has attempted to recreate it when people have for basically everything else. AFAICT the only real other standard is Active Directory.

And secondly, is there a standard or protocol for offloading access control? I see Authelia allows you to contol access by url patterns, but I'd expect e.g. a fileserver to instead reach out to the LDAP server and check permissions based on the authenticated user id and keys in the database. This seems like the opposite of oauth2 which is for a server getting access itself to a 3rd party service.

alex33054• 2 years ago

Recently I looked into having a relatively simple SSO setup for my homelab. My main objective is that I could easily login with Google or GitHub auth. At my previous job I used both JetBrains Hub [1] and Keycloak but I found both of them a bit of a PITA to setup.

JetBrains Hub was really, really easy to get going. As was my previous experience with them. The only thing that annoyed me was the lack of a latest tag on their Docker registry. Don't get me wrong, pinned versions are great, but for my personal use I mostly just want to update all my Docker containers in one go.

On the other hand I found Keycloak very cumbersome to get going. It was pretty easy in dev mode, but I stumbled to get it going in production. AFAIK it had something to do with the wildcard Let's Encrypt cert that I tried to use. But after a couple of hours, I just gave up.

I finally went with Dex [2]. I had previously put it off because of the lack of documentation, but in the end it was extremely easy to setup. It just required some basic YAML, a SQLite database and a (sub)domain. I combined Dex with the excellent OAuth2 Proxy and a custom Nginx (Proxy Manager) template for an easy two line SSO configuration on all of my internal services. I also created an Dex Docker template for unRAID [4].

In addition to this setup, I also added Cloudflare Access and WAF outside of my home to add some security. I only want to add some CrowdSec to get a little more insights.

1. https://www.jetbrains.com/hub/

2. https://dexidp.io/

3. https://github.com/oauth2-proxy/oauth2-proxy

4. https://github.com/alex3305/unraid-docker-templates

apitman8• 2 years ago

What features does oauth2-proxy provide that Dex is missing?

alex33054• 2 years ago

Dex only acts as a federated identity provider. Unlike oauth2-proxy which acts as a service provider for services that don't have authentication themselves.

mnming• 2 years ago

I use obligator with ephemeral storage, no db, 100% code driven setup.

In my opinion this is the simplist option.

https://github.com/lastlogin-io/obligator

alex33054• 2 years ago

Great addition. I remember that I also looked at Obligator and saved it to my bookmarks. But I decided against it because IMHO the project was just a bit too young. Normally I tend to ignore that, but I really didn't want to switch auth/SSO solutions in a couple of months time because of a lack of maintenance or something like that.

raffraffraff3• 2 years ago

My boss recently called Keycloak "the gift that keeps on giving", but he was actually commenting on how there's a new ticket in jira for figuring out how the f*?k to do something.

Having said that, I have terraform that creates an EKS cluster, deploys Keycloak , creates clients (SAML/OIDC), adds external identity providers, sets up an AWS IAM Identity Provider for it etc. That makes it extremely easy to use once you've figured out (a) what it can do, (b) how to do it in the ui, (c) how to get mrparkers Terraform provider to do it for you.

davidgf2• 2 years ago

By any chance, is that Terraform open sourced somewhere? It's for a friend :)

raffraffraff3• 2 years ago

haha, nope unfortunately. But I also use an odd method of keeping my terraform code dry via Hiera (yes, the Puppet thing). If you're interested I can find out if it's ok to open source it.

lakomen• 2 years ago

You don't need a bazillion keycloak instances, it has realms.

1 keycloak instance can have many realms.

I won't get into the nonsense of having a single database server per any instance (not limited to keycloak). Such a waste of resources.

You can have a system, postgres in this case, and make it listen on the docker iface, set it up to launch after and require docker.service.

The nginx conf was interesting and I'll adjust mine.

topspin• 2 years ago

Some additional things that someone might find useful:

Keycloak supports separating token endpoints (the OAUTH2/OIDC URLS used for tokens) and the built-in login challenge pages from Keycloak's admin console and the REST API. In other words, you can offer the token endpoints and login service to the public and isolate all the admin and backend stuff to a different hostname and/or URL scheme. Have a look at the KC_HOSTNAME_ADMIN[_URL] config option(s).

Keycloak has a capability called Authorization Services, an implementation of User Managed Access (UMA2). It's opt-in and probably 99% of Keycloak users don't know it exists. It can be used to implement fine-grained authorization schemes on top of OAUTH.

Klathmon• 2 years ago

I've found that the realms in keycloak doesn't scale quite as well as we would have wanted.

There is some kind of slowdown, and after around 200 realms things start breaking and startup time starts growing uncontrollably.

There's a good chance it's an issue in our setup (which is fairly complex), but every time we look at it we trace the slowdown back into keycloak itself

turtles3• 2 years ago

Just letting you know it's not you - this is a well known long standing issue with keycloak. Typically users see a significant performance cliff at around 300-400 realms. While one realm is not necessarily the same as one tenant in keycloak, it does make it a significantly larger headache to support multi tenant with SSO integrations in a single realm.

I'm afraid I can't give you more details than that, we just moved on from keycloak at that point.

mooreds11• 2 years ago

1 keycloak instance can have many realms.

For people not familiar with keycloak, keycloak realms are equivalent to what other auth providers call tenants (Auth0, FusionAuth [which I work for]) or user pools (Cognito). Basically a segmented set of users and configuration related to those users.

silverwind• 2 years ago

Why is `docker run` "unusual in production"? I prefer it over `docker-compose` because it eliminates one mostly useless layer of abstraction.

Helmut100013• 2 years ago

Just one reason for me is that I can add the docker-compose.yml to git to track changes over time and have a more reproducible setup.

zerof1l• 2 years ago

Because when you run 10 services most of whom require at least one supporting service and for each service you need to specify at least 5 different options (volumes, resource limits, health check, depends on, mac address, IP address, etc); with just `docker run` you will have a mess. It's much simpler to have a docker-compose file per service with all of its dependent services.

The docker compose to plain docker run is the same as C/C++ to Assembly.

jayemar• 2 years ago

SSO is Single Sign On for those as lost as me. SSO allows a user to log in one time and then access multiple services securely.

durable_queue2• 2 years ago

A problem I've had trying to do this for local dev is that the DNS name of the Keycloak server is "keycloak" inside of the Docker network, but "localhost" from the the outside. The user's browser will be redirected to localhost (since it's outside of the Docker network) but then there is a mismatch between hosts (it expects "keycloak" not "localhost") when it comes to an API server verifying the token.

Anyone figured this out?

mooreds11• 2 years ago

I haven't tried this, but could you modify your /etc/hosts file (or analogous file on whatever operating system) to have `keycloak` as a valid hostname on your local computer? So that both within the docker container and in your host computer, `keycloak` was the hostname of the keycloak server?

durable_queue2• 2 years ago

Always an option, but I dislike changing global settings on the system. It makes it harder to hop between projects and it's slower when onboarding.

eYrKEC2• 2 years ago

You need to configure the "client" in keyclock that corresponds with you front-end.

RecycledEle• 2 years ago

FYI, SSO=Single Sign-On

mathfailure• 2 years ago

For your information, FYI=For your information

tzahifadida2• 2 years ago

I am using keycloak for quite a while. The main problem I have with it is that you can't get a link to reset a password, you have to issue an api that does it for you. In fact that is how most of the product goes. It is very opinionated. Making it a cluster is also not easy, though I did it and it works ok. Another issue is that the realms has a limit. Though you can spin up an instance every 200 realms but it is not for me... Instead, I just use it for login and do the roles internally in my app for every tenant<>user<>Role but then I get back to thinking, this was an overkill... but a login system that is secured is difficult and I don't want to deal with that...

I am complaining but what is the alternative? Do it all yourself? It is either too risky or too difficult...

Helmut100013• 2 years ago

Is this really true? Reading [1] they say:

Forgot Password: If you enable it, users are able to reset their credentials if they forget their password or lose their OTP generator. Go to the Realm Settings left menu item, and click on the Login tab. Switch on the Forgot Password switch.

[1] https://wjw465150.gitbooks.io/keycloak-documentation/content...

tzahifadida2• 2 years ago

As I said, very opinionated. Meaning you have to use their way. So, for example, if I want to add turnstile bot protection to the reset password screen so your aws smtp won't be abused, I have to write a plugin instead of just getting the url to send myself.

makkesk8• 2 years ago

After working with Keycloak for a couple of years I honestly got fed up with all it's quirks and started to look at alternatives, Authentik and many more looked promising but Zitadel[1] caught my eye and I've never looked back since.

[1] https://zitadel.com/blog/zitadel-vs-keycloak

mffap3• 2 years ago

Nice to hear. Glad you like it. What was the winning thing for you?

reactordev3• 2 years ago

The issue with Keycloak is that it’s been around a while and has gone through a ton of changes. While it started as a JBOSS project, its usefulness as an IdP shines in on-prem cluster auth. However, that’s where I would stop. I implemented Keycloak at scale on AWS ECS for a Fortune 500 department and it was unholy war for 1,000 years getting it to cluster properly. DNS discovery didn’t work right. Cluster discovery was over UDP (which didn’t work in our cloud environments). Stateful login on one server was missing from the others so dumb load balancing was off the table - sticky sessions was the only way. While it’s easy to docker run Keycloak and plug it in like Auth0, it’s like buying a 1996 Ford F-150 with 250,000 miles. It runs. It works. But Jesus is it a maintenance madonna.

reactordev3• 2 years ago

OAuth with OpenID Connect and being able to add apps and clients to a realm was its saving grace and the only reason we kept it around.

silverquiet• 2 years ago

I did it at quite small scale, but within an on-prem docker swarm. It was indeed a pain because if I remember correctly the default discovery uses multicast which is not enabled on typical cloud networks or on a Swarm/Kubernetes overlay network. I looked at database pings where they'd use your RDMS for a sort of quorum mechanism, but that seemed very brittle and I got the impression it was more of a last-resort type thing.

I was able to use the kubernetes cluster driver which uses the Swarm cluster's DNS for node discovery. It was indeed quite a pain to get working, but since then has been solid as far as I know. I believe there is also a native ec2 networking driver these days, but that is not something that I explored.

bird_person_• 2 years ago

Cluster discovery was over UDP (which didn’t work in our cloud environments)

Ouch, we are only allowed UDP for DNS.

mooreds11• 2 years ago

I've heard there have been improvements since it fully moved to quarkus. When did you do that deployment to ECS?

reactordev3• 2 years ago

2017-2019, by 2020 we moved to another IdP middleman.

seanieb• 2 years ago

The idea that Keycloak solves security issues makes me giggle. It's CVE's should shed some light on what I mean.

- https://www.cvedetails.com/vulnerability-list/vendor_id-25/p...

bjconlan• 2 years ago

It's a double edged sword. A closed source non-transparent solution without a reported cve is also laughable as "secure".

Also the most recent release 22.0.2 only has 3 (known) vulnerabilities. https://www.cvedetails.com/vulnerability-list/vendor_id-25/p...

epylar• 2 years ago

most recent release is 23.0.6

goldman7911• 2 years ago

I got a hard time trying to integrate Spring Security 3.1 and Keycloak. All examples are based on @Deprecated connectors. Even in Spring Security there are a lot of huge changes ongoing.

cycomanic• 2 years ago

After looking for a solution for my home lab for a while I ended up with Authentik. It's a comparatively new kid, but it was very easy to set up and the documentation is really excellent!

tanberry• 2 years ago

Thanks for the nod to the authentik documentation! That's my primary role at authentik... we are going to do some restructuring soon, with a goal to keep the current level of excellence while adding in all the new features coming up in our 2024.2.x release, plus add more How To (procedurals). We would appreciate any feedback, and of course we'd love any contributions to our docs in GitHub!

apitman8• 2 years ago

I made a (incomplete) comparison table of various self-hostable OpenID Connect servers[0].

One of the surprising things to me is just how massive the Keycloak codebase is.

[0] https://github.com/lastlogin-io/obligator?tab=readme-ov-file...

aborsy• 2 years ago

Anyone using teleport?

It’s not exactly a reverse proxy, but it does add a layer of authentication to web applications, ssh, and remote desktop.

Keycloak SSO with Docker Compose and Nginx

Related Stories