mirror of
https://github.com/funkypenguin/geek-cookbook/
synced 2026-01-04 12:29:20 +00:00
Improve Keycloak recipe
Signed-off-by: David Young <davidy@funkypenguin.co.nz>
This commit is contained in:
David Young
@@ -1,20 +1,20 @@
|
||||
---
|
||||
title: Integrate LDAP server with Keycloak for user federation
|
||||
description: Here's how we'll add an LDAP provider to our KeyCloak server for user federation.
|
||||
description: Here's how we'll add an LDAP provider to our Keycloak server for user federation.
|
||||
---
|
||||
# Authenticate KeyCloak against OpenLDAP
|
||||
# Authenticate Keycloak against OpenLDAP
|
||||
|
||||
!!! warning
|
||||
This is not a complete recipe - it's an **optional** component of the [Keycloak recipe](/recipes/keycloak/), but has been split into its own page to reduce complexity.
|
||||
|
||||
KeyCloak gets really sexy when you integrate it into your [OpenLDAP](/recipes/openldap/) stack (_also, it's great not to have to play with ugly LDAP tree UIs_). Note that OpenLDAP integration is **not necessary** if you want to use KeyCloak with [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/) - all you need for that is [local users](/recipes/keycloak/create-user/), and an [OIDC client](http://localhost:8000/recipes/keycloak/setup-oidc-provider/).
|
||||
Keycloak gets really sexy when you integrate it into your [OpenLDAP](/recipes/openldap/) stack (_also, it's great not to have to play with ugly LDAP tree UIs_). Note that OpenLDAP integration is **not necessary** if you want to use Keycloak with [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/) - all you need for that is [local users](/recipes/keycloak/create-user/), and an [OIDC client](http://localhost:8000/recipes/keycloak/setup-oidc-provider/).
|
||||
|
||||
## Ingredients
|
||||
|
||||
!!! Summary
|
||||
Existing:
|
||||
|
||||
* [X] [KeyCloak](/recipes/keycloak/) recipe deployed successfully
|
||||
* [X] [Keycloak](/recipes/keycloak/) recipe deployed successfully
|
||||
|
||||
New:
|
||||
|
||||
@@ -28,11 +28,11 @@ You start in the "Master" realm - but mouseover the realm name, to a dropdown bo
|
||||
|
||||
### Create Realm
|
||||
|
||||
{ loading=lazy }
|
||||
{ loading=lazy }
|
||||
|
||||
Enter a name for your new realm, and click "_Create_":
|
||||
|
||||
{ loading=lazy }
|
||||
{ loading=lazy }
|
||||
|
||||
### Setup User Federation
|
||||
|
||||
@@ -48,24 +48,24 @@ Once in the desired realm, click on **User Federation**, and click **Add Provide
|
||||
|
||||
Save your changes, and then navigate back to "User Federation" > Your LDAP name > Mappers:
|
||||
|
||||
{ loading=lazy }
|
||||
{ loading=lazy }
|
||||
|
||||
For each of the following mappers, click the name, and set the "_Read Only_" flag to "_Off_" (_this enables 2-way sync between KeyCloak and OpenLDAP_)
|
||||
For each of the following mappers, click the name, and set the "_Read Only_" flag to "_Off_" (_this enables 2-way sync between Keycloak and OpenLDAP_)
|
||||
|
||||
* last name
|
||||
* username
|
||||
* email
|
||||
* first name
|
||||
|
||||
{ loading=lazy }
|
||||
{ loading=lazy }
|
||||
|
||||
## Summary
|
||||
|
||||
We've setup a new realm in KeyCloak, and configured read-write federation to an [OpenLDAP](/recipes/openldap/) backend. We can now manage our LDAP users using either KeyCloak or LDAP directly, and we can protect vulnerable services using [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/).
|
||||
We've setup a new realm in Keycloak, and configured read-write federation to an [OpenLDAP](/recipes/openldap/) backend. We can now manage our LDAP users using either Keycloak or LDAP directly, and we can protect vulnerable services using [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/).
|
||||
|
||||
!!! Summary
|
||||
Created:
|
||||
|
||||
* [X] KeyCloak realm in read-write federation with [OpenLDAP](/recipes/openldap/) directory
|
||||
* [X] Keycloak realm in read-write federation with [OpenLDAP](/recipes/openldap/) directory
|
||||
|
||||
--8<-- "recipe-footer.md"
|
||||
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: Create users in Keycloak
|
||||
description: Unless you plan to authenticate against an outside provider (OpenLDAP, below, for example_), you'll want to create some local users..
|
||||
---
|
||||
# Create Keycloak Users
|
||||
|
||||
!!! warning
|
||||
This is not a complete recipe - it's an optional component of the [Keycloak recipe](/recipes/keycloak/), but has been split into its own page to reduce complexity.
|
||||
|
||||
Unless you plan to authenticate against an outside provider (_[OpenLDAP](/recipes/keycloak/authenticate-against-openldap/), below, for example_), you'll want to create some local users..
|
||||
|
||||
## Ingredients
|
||||
|
||||
!!! Summary
|
||||
Existing:
|
||||
|
||||
* [X] [KeyCloak](/recipes/keycloak/) recipe deployed successfully
|
||||
|
||||
### Create User
|
||||
|
||||
Within the "Master" realm (_no need for more realms yet_), navigate to **Manage** -> **Users**, and then click **Add User** at the top right:
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
Populate your new user's username (it's the only mandatory field)
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
### Set User Credentials
|
||||
|
||||
Once your user is created, to set their password, click on the "**Credentials**" tab, and procede to reset it. Set the password to non-temporary, unless you like extra work!
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
## Summary
|
||||
|
||||
We've setup users in KeyCloak, which we can now use to authenticate to KeyCloak, when it's used as an [OIDC Provider](/recipes/keycloak/setup-oidc-provider/), potentially to secure vulnerable services using [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/).
|
||||
|
||||
!!! Summary
|
||||
Created:
|
||||
|
||||
* [X] Username / password to authenticate against [KeyCloak](/recipes/keycloak/)
|
||||
|
||||
--8<-- "recipe-footer.md"
|
||||
@@ -1,32 +1,31 @@
|
||||
---
|
||||
title: How to setup OIDC server in Docker with KeyCloak
|
||||
description: Kick-ass OIDC and identity management
|
||||
title: Run Keycloak behind traefik in Docker
|
||||
---
|
||||
|
||||
# KeyCloak
|
||||
# Keycloak (in Docker Swarm)
|
||||
|
||||
[KeyCloak](https://www.keycloak.org/) is "_an open source identity and access management solution_". Using a local database, or a variety of backends (_think [OpenLDAP](/recipes/openldap/)_), you can provide Single Sign-On (SSO) using OpenID, OAuth 2.0, and SAML.
|
||||
[Keycloak](https://www.keycloak.org/) is "_an open source identity and access management solution_". Using a local database, or a variety of backends (_think [OpenLDAP](/recipes/openldap/)_), you can provide Single Sign-On (SSO) using OpenID, OAuth 2.0, and SAML.
|
||||
|
||||
KeyCloak's OpenID provider can also be used in combination with [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/), to protect [vulnerable services](/recipes/autopirate/nzbget/) with an extra layer of authentication.
|
||||
Keycloak's OpenID provider can also be used in combination with [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/), to protect [vulnerable services](/recipes/autopirate/nzbget/) with an extra layer of authentication.
|
||||
|
||||
{ loading=lazy }
|
||||
{ loading=lazy }
|
||||
|
||||
--8<-- "recipe-standard-ingredients.md"
|
||||
|
||||
## Preparation
|
||||
## Setup
|
||||
|
||||
### Setup data locations
|
||||
### Filesystem paths
|
||||
|
||||
We'll need several directories to bind-mount into our container for both runtime and backup data, so create them as per the following example
|
||||
We'll need several directories to bind-mount into our container for both runtime and backup data, so create them as per the following example:
|
||||
|
||||
```bash
|
||||
mkdir -p /var/data/runtime/keycloak/database
|
||||
mkdir -p /var/data/keycloak/database-dump
|
||||
```
|
||||
|
||||
### Prepare environment
|
||||
### Environment vars
|
||||
|
||||
Create `/var/data/config/keycloak/keycloak.env`, and populate with the following variables, customized for your own domain structure.
|
||||
Create `/var/data/config/keycloak/keycloak.env`, and populate with the following example variables, customized for your own domain structure.
|
||||
|
||||
```bash
|
||||
# Technically, this could be auto-detected, but we prefer to be prescriptive
|
||||
@@ -59,9 +58,9 @@ BACKUP_NUM_KEEP=7
|
||||
BACKUP_FREQUENCY=1d
|
||||
```
|
||||
|
||||
### Setup Docker Swarm
|
||||
## Docker compose example
|
||||
|
||||
Create a docker swarm config file in docker-compose syntax (v3), something like this:
|
||||
Create a docker swarm config file in docker-compose syntax (v3), something like this example:
|
||||
|
||||
--8<-- "premix-cta.md"
|
||||
|
||||
@@ -132,14 +131,53 @@ networks:
|
||||
|
||||
--8<-- "reference-networks.md"
|
||||
|
||||
## Serving
|
||||
## Running
|
||||
|
||||
### Launch KeyCloak stack
|
||||
### Launch Keycloak stack
|
||||
|
||||
Launch the KeyCloak stack by running `docker stack deploy keycloak -c <path -to-docker-compose.yml>`
|
||||
Launch the Keycloak stack by running `docker stack deploy keycloak -c <path -to-docker-compose.yml>`
|
||||
|
||||
Log into your new instance at `https://YOUR-FQDN`, and login with the user/password you defined in `keycloak.env`.
|
||||
|
||||
### Create User
|
||||
|
||||
!!! question "Why are we adding a user when I have an admin user already?"
|
||||
Do you keep a spare set of house keys somewhere _other_ than your house? Do you login as `root` onto all your systems? Think of this as the same prinicple - lock the literal `admin` account away somewhere as a "password of last resort", and create a new user for your day-to-day interaction with Keycloak.
|
||||
|
||||
Within the "Master" realm (_no need for more realms yet_), navigate to **Manage** -> **Users**, and then click **Add User** at the top right:
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
Populate your new user's username (it's the only mandatory field)
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
#### Set User Credentials
|
||||
|
||||
Once your user is created, to set their password, click on the "**Credentials**" tab, and procede to reset it. Set the password to non-temporary, unless you like extra work!
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
## Tips
|
||||
|
||||
### Traefik
|
||||
|
||||
Keycloak can be used with Traefik in two ways..
|
||||
|
||||
#### Keycloak behind Traefik
|
||||
|
||||
You'll notice that the docker compose example above includes labels for both Traefik v2 and Traefik v2. You obviously don't need both (*although it wont't hurt*), but make sure you update the example domain in the Traefik labels. Keycloak should work behind Traefik without any further customization.
|
||||
|
||||
#### Keycloak as Traefik middleware
|
||||
|
||||
Irrespective of whether Keycloak itself is behind Traefik, you can secure access to **other** services [behind Traefik using Keycloak][tfa-keycloak], using the [Traefik Forward Auth][tfa] middleware. Other similar middleware solutions are traefik-gatekeeper, and oauth2-proxy.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
Something didn't work? Try the following:
|
||||
|
||||
1. Confirm that Keycloak did, in fact, start, by looking at the state of the stack, with `docker stack ps keycloak --no-trunc`
|
||||
|
||||
--8<-- "recipe-footer.md"
|
||||
|
||||
[^1]: For more geeky {--pain--}{++fun++}, try integrating KeyCloak with [OpenLDAP][openldap] for an authentication backend!
|
||||
[^1]: For more geeky {--pain--}{++fun++}, try integrating Keycloak with [OpenLDAP][openldap] for an authentication backend!
|
||||
|
||||
@@ -1,20 +1,20 @@
|
||||
---
|
||||
title: How to setup OIDC provider in KeyCloak
|
||||
description: Having an authentication provider is not much use until you start authenticating things against it! In order to authenticate against KeyCloak using OpenID Connect (OIDC), which is required for Traefik Forward Auth, we'll setup a client in KeyCloak...
|
||||
title: How to setup OIDC provider in Keycloak
|
||||
description: Having an authentication provider is not much use until you start authenticating things against it! In order to authenticate against Keycloak using OpenID Connect (OIDC), which is required for Traefik Forward Auth, we'll setup a client in Keycloak...
|
||||
---
|
||||
# Add OIDC Provider to KeyCloak
|
||||
# Add OIDC Provider to Keycloak
|
||||
|
||||
!!! warning
|
||||
This is not a complete recipe - it's an optional component of the [Keycloak recipe](/recipes/keycloak/), but has been split into its own page to reduce complexity.
|
||||
|
||||
Having an authentication provider is not much use until you start authenticating things against it! In order to authenticate against KeyCloak using OpenID Connect (OIDC), which is required for [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/), we'll setup a client in KeyCloak...
|
||||
Having an authentication provider is not much use until you start authenticating things against it! In order to authenticate against Keycloak using OpenID Connect (OIDC), which is required for [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/), we'll setup a client in Keycloak...
|
||||
|
||||
## Ingredients
|
||||
|
||||
!!! Summary
|
||||
Existing:
|
||||
|
||||
* [X] [KeyCloak](/recipes/keycloak/) recipe deployed successfully
|
||||
* [X] [Keycloak](/recipes/keycloak/) recipe deployed successfully
|
||||
|
||||
New:
|
||||
|
||||
@@ -30,7 +30,7 @@ Within the "Master" realm (*no need for more realms yet*), navigate to **Clients
|
||||
|
||||
Enter a name for your client (*remember, we're authenticating **applications** now, not users, so use an application-specific name*):
|
||||
|
||||
{ loading=lazy }
|
||||
{ loading=lazy }
|
||||
|
||||
### Configure Client
|
||||
|
||||
@@ -39,21 +39,21 @@ Once your client is created, set at **least** the following, and click **Save**
|
||||
* **Access Type** : Confidential
|
||||
* **Valid Redirect URIs** : <The URIs you want to protect\>
|
||||
|
||||
{ loading=lazy }
|
||||
{ loading=lazy }
|
||||
|
||||
### Retrieve Client Secret
|
||||
|
||||
Now that you've changed the access type, and clicked **Save**, an additional **Credentials** tab appears at the top of the window. Click on the tab, and capture the KeyCloak-generated secret. This secret, plus your client name, is required to authenticate against KeyCloak via OIDC.
|
||||
Now that you've changed the access type, and clicked **Save**, an additional **Credentials** tab appears at the top of the window. Click on the tab, and capture the Keycloak-generated secret. This secret, plus your client name, is required to authenticate against Keycloak via OIDC.
|
||||
|
||||
{ loading=lazy }
|
||||
{ loading=lazy }
|
||||
|
||||
## Summary
|
||||
|
||||
We've setup an OIDC client in KeyCloak, which we can now use to protect vulnerable services using [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/). The OIDC URL provided by KeyCloak in the master realm, is `https://<your-keycloak-url>/realms/master/.well-known/openid-configuration`
|
||||
We've setup an OIDC client in Keycloak, which we can now use to protect vulnerable services using [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/). The OIDC URL provided by Keycloak in the master realm, is `https://<your-keycloak-url>/realms/master/.well-known/openid-configuration`
|
||||
|
||||
!!! Summary
|
||||
Created:
|
||||
|
||||
* [X] Client ID and Client Secret used to authenticate against KeyCloak with OpenID Connect
|
||||
* [X] Client ID and Client Secret used to authenticate against Keycloak with OpenID Connect
|
||||
|
||||
--8<-- "recipe-footer.md"
|
||||
|
||||
@@ -21,7 +21,7 @@ This recipe combines the raw power of OpenLDAP with the flexibility and features
|
||||
|
||||
## What's the takeaway?
|
||||
|
||||
What you'll end up with is a directory structure which will allow integration with popular tools (_[NextCloud](/recipes/nextcloud/), [Kanboard](/recipes/kanboard/), [Gitlab](/recipes/gitlab/), etc_), as well as with KeyCloak (_an upcoming recipe_), for **true** SSO.
|
||||
What you'll end up with is a directory structure which will allow integration with popular tools (_[NextCloud](/recipes/nextcloud/), [Kanboard](/recipes/kanboard/), [Gitlab](/recipes/gitlab/), etc_), as well as with Keycloak (_an upcoming recipe_), for **true** SSO.
|
||||
|
||||
--8<-- "recipe-standard-ingredients.md"
|
||||
|
||||
@@ -377,9 +377,9 @@ networks:
|
||||
!!! warning
|
||||
**Normally**, we set unique static subnets for every stack you deploy, and put the non-public facing components (like databases) in an dedicated <stack\>_internal network. This avoids IP/gateway conflicts which can otherwise occur when you're creating/removing stacks a lot. See [my list](/reference/networks/) here.
|
||||
|
||||
However, you're likely to want to use OpenLdap with KeyCloak, whose JBOSS startup script assumes a single interface, and will crash in a ball of 🔥 if you try to assign multiple interfaces to the container.
|
||||
However, you're likely to want to use OpenLdap with Keycloak, whose JBOSS startup script assumes a single interface, and will crash in a ball of 🔥 if you try to assign multiple interfaces to the container.
|
||||
|
||||
Since we're going to want KeyCloak to be able to talk to OpenLDAP, we have no choice but to leave the OpenLDAP container on the "traefik_public" network. We can, however, create **another** overlay network (_auth_internal, see below_), add it to the openldap container, and use it to provide OpenLDAP access to our other stacks.
|
||||
Since we're going to want Keycloak to be able to talk to OpenLDAP, we have no choice but to leave the OpenLDAP container on the "traefik_public" network. We can, however, create **another** overlay network (_auth_internal, see below_), add it to the openldap container, and use it to provide OpenLDAP access to our other stacks.
|
||||
|
||||
Create **another** stack config file (```/var/data/config/openldap/auth.yml```) containing just the auth_internal network, and a dummy container:
|
||||
|
||||
@@ -422,6 +422,6 @@ You've now setup your OpenLDAP directory structure, and your administration inte
|
||||
|
||||
Create your users using the "**New User**" button.
|
||||
|
||||
[^1]: [The KeyCloak](/recipes/keycloak/authenticate-against-openldap/) recipe illustrates how to integrate KeyCloak with your LDAP directory, giving you a cleaner interface to manage users, and a raft of SSO / OAuth features.
|
||||
[^1]: [The Keycloak](/recipes/keycloak/authenticate-against-openldap/) recipe illustrates how to integrate Keycloak with your LDAP directory, giving you a cleaner interface to manage users, and a raft of SSO / OAuth features.
|
||||
|
||||
--8<-- "recipe-footer.md"
|
||||
|
||||
Reference in New Issue
Block a user