public/geek-cookbook
1
0
Fork 0
mirror of https://github.com/funkypenguin/geek-cookbook/ synced 2025-12-13 17:56:26 +00:00
Code Issues Releases Wiki Activity

Improve Keycloak recipe

Browse Source 
Signed-off-by: David Young <davidy@funkypenguin.co.nz>
This commit is contained in:
David Young
2022-07-12 16:00:01 +12:00
parent b807d87520
commit 45f499c221
15 changed files with 102 additions and 109 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
_snippets/recipe-standard-ingredients.md
View File

@@ -1,4 +1,4 @@
## Ingredients ## Requirements
!!! summary "Ingredients" !!! summary "Ingredients"
Already deployed: Already deployed:

2
manuscript/CHANGELOG.md
View File

@@ -21,7 +21,7 @@ Recipe | Description
Recipe | Description | Date Recipe | Description | Date
----------------------------|---------------------------------------------------------------------------------|-------------- ----------------------------|---------------------------------------------------------------------------------|--------------
[Minio][minio] | Major update to Minio recipe, for new Console UI and Traefik v2 | _22 Oct 2021_ [Minio][minio] | Major update to Minio recipe, for new Console UI and Traefik v2 | _22 Oct 2021_
[Traefik Forward Auth][tfa] | Major update for Traefik v2, included instructions for Dex, Google, KeyCloak | _29 Jan 2021_ [Traefik Forward Auth][tfa] | Major update for Traefik v2, included instructions for Dex, Google, Keycloak | _29 Jan 2021_
[Autopirate][autopirate] | Updated all components for Traefik v2 labels | _29 Jan 2021_ [Autopirate][autopirate] | Updated all components for Traefik v2 labels | _29 Jan 2021_
[Portainer][portainer] | Bump to version 2, bringing "expert simplicity" to your Docker stack management | _25 Jan 2021_ [Portainer][portainer] | Bump to version 2, bringing "expert simplicity" to your Docker stack management | _25 Jan 2021_

2
manuscript/docker-swarm/traefik-forward-auth/dex-static.md
View File

@@ -4,7 +4,7 @@ description: Traefik forward auth needs an authentication backend, but if you do
--- ---
# Traefik Forward Auth for SSO with Dex (Static) # Traefik Forward Auth for SSO with Dex (Static)
[Traefik Forward Auth](/docker-swarm/traefik-forward-auth/) is incredibly useful to secure services with an additional layer of authentication, provided by an OIDC-compatible provider. The simplest possible provider is a self-hosted instance of [CoreOS's Dex](https://github.com/dexidp/dex), configured with a static username and password. This recipe will "get you started" with Traefik Forward Auth, providing a basic authentication layer. In time, you might want to migrate to a "public" provider, like [Google][tfa-google], or GitHub, or to a [KeyCloak][keycloak] installation. [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/) is incredibly useful to secure services with an additional layer of authentication, provided by an OIDC-compatible provider. The simplest possible provider is a self-hosted instance of [CoreOS's Dex](https://github.com/dexidp/dex), configured with a static username and password. This recipe will "get you started" with Traefik Forward Auth, providing a basic authentication layer. In time, you might want to migrate to a "public" provider, like [Google][tfa-google], or GitHub, or to a [Keycloak][keycloak] installation.
--8<-- "recipe-tfa-ingredients.md" --8<-- "recipe-tfa-ingredients.md"

6
manuscript/docker-swarm/traefik-forward-auth/index.md
View File

@@ -46,12 +46,12 @@ This clever workaround only works under 2 conditions:
## Authentication Providers ## Authentication Providers
Traefik Forward Auth needs to authenticate an incoming user against a provider. A provider can be something as simple as a self-hosted [dex][tfa-dex-static] instance with a single static username/password, or as complex as a [KeyCloak][keycloak] instance backed by [OpenLDAP][openldap]. Here are some options, in increasing order of complexity... Traefik Forward Auth needs to authenticate an incoming user against a provider. A provider can be something as simple as a self-hosted [dex][tfa-dex-static] instance with a single static username/password, or as complex as a [Keycloak][keycloak] instance backed by [OpenLDAP][openldap]. Here are some options, in increasing order of complexity...
* [Authenticate Traefik Forward Auth against a self-hosted Dex instance with static usernames and passwords][tfa-dex-static] * [Authenticate Traefik Forward Auth against a self-hosted Dex instance with static usernames and passwords][tfa-dex-static]
* [Authenticate Traefik Forward Auth against a whitelist of Google accounts][tfa-google] * [Authenticate Traefik Forward Auth against a whitelist of Google accounts][tfa-google]
* [Authenticate Traefik Forward Auth against a self-hosted KeyCloak instance][tfa-keycloak] with an optional [OpenLDAP backend][openldap] * [Authenticate Traefik Forward Auth against a self-hosted Keycloak instance][tfa-keycloak] with an optional [OpenLDAP backend][openldap]
--8<-- "recipe-footer.md" --8<-- "recipe-footer.md"
[^1]: Authhost mode is specifically handy for Google authentication, since Google doesn't permit wildcard redirect_uris, like [KeyCloak][keycloak] does. [^1]: Authhost mode is specifically handy for Google authentication, since Google doesn't permit wildcard redirect_uris, like [Keycloak][keycloak] does.

12
manuscript/docker-swarm/traefik-forward-auth/keycloak.md
View File

@@ -2,9 +2,9 @@
title: SSO with traefik forward auth with Keycloak title: SSO with traefik forward auth with Keycloak
description: Traefik forward auth can selectively SSO your Docker services against an authentication backend using OIDC, and Keycloak is a perfect, self-hosted match. description: Traefik forward auth can selectively SSO your Docker services against an authentication backend using OIDC, and Keycloak is a perfect, self-hosted match.
--- ---
# Traefik Forward Auth with KeyCloak for SSO # Traefik Forward Auth with Keycloak for SSO
While the [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/) recipe demonstrated a quick way to protect a set of explicitly-specified URLs using OIDC credentials from a Google account, this recipe will illustrate how to use your own KeyCloak instance to secure **any** URLs within your DNS domain. While the [Traefik Forward Auth](/docker-swarm/traefik-forward-auth/) recipe demonstrated a quick way to protect a set of explicitly-specified URLs using OIDC credentials from a Google account, this recipe will illustrate how to use your own Keycloak instance to secure **any** URLs within your DNS domain.
!!! tip "Keycloak with Traefik" !!! tip "Keycloak with Traefik"
Did you land here from a search, looking for information about using Keycloak with Traefik? All this and more is covered in the [Keycloak][keycloak] recipe! Did you land here from a search, looking for information about using Keycloak with Traefik? All this and more is covered in the [Keycloak][keycloak] recipe!
@@ -71,7 +71,7 @@ Redeploy traefik with `docker stack deploy traefik-app -c /var/data/traefik/trae
### Test ### Test
Browse to <https://whoami.example.com> (_obviously, customized for your domain and having created a DNS record_), and all going according to plan, you'll be redirected to a KeyCloak login. Once successfully logged in, you'll be directed to the basic whoami page. Browse to <https://whoami.example.com> (_obviously, customized for your domain and having created a DNS record_), and all going according to plan, you'll be redirected to a Keycloak login. Once successfully logged in, you'll be directed to the basic whoami page.
### Protect services ### Protect services
@@ -87,13 +87,13 @@ And re-deploy your services :)
## Summary ## Summary
What have we achieved? By adding an additional three simple labels to any service, we can secure any service behind our KeyCloak OIDC provider, with minimal processing / handling overhead. What have we achieved? By adding an additional three simple labels to any service, we can secure any service behind our Keycloak OIDC provider, with minimal processing / handling overhead.
!!! summary "Summary" !!! summary "Summary"
Created: Created:
* [X] Traefik-forward-auth configured to authenticate against KeyCloak * [X] Traefik-forward-auth configured to authenticate against Keycloak
[^1]: KeyCloak is very powerful. You can add 2FA and all other clever things outside of the scope of this simple recipe ;) [^1]: Keycloak is very powerful. You can add 2FA and all other clever things outside of the scope of this simple recipe ;)
--8<-- "recipe-footer.md" --8<-- "recipe-footer.md"

2
manuscript/kubernetes/cluster/index.md
View File

@@ -34,7 +34,7 @@ Cloud providers make it easy to connect their storage solutions to your cluster,
### Services ### Services
Some things just "work better" in a cloud provider environment. For example, to run a highly available Postgres instance on Kubernetes requires at least 3 nodes, and 3 x storage, plus manual failover/failback in the event of an actual issue. This can represent a huge cost if you simply need a PostgreSQL database to provide (*for example*) a backend to an authentication service like KeyCloak. Cloud providers will have a range of managed database solutions which will cost far less than do-it-yourselfing, and integrate easily and securely into their kubernetes offerings. Some things just "work better" in a cloud provider environment. For example, to run a highly available Postgres instance on Kubernetes requires at least 3 nodes, and 3 x storage, plus manual failover/failback in the event of an actual issue. This can represent a huge cost if you simply need a PostgreSQL database to provide (*for example*) a backend to an authentication service like Keycloak. Cloud providers will have a range of managed database solutions which will cost far less than do-it-yourselfing, and integrate easily and securely into their kubernetes offerings.
### Summary ### Summary

2
manuscript/kubernetes/deployment/flux/design.md
View File

@@ -53,7 +53,7 @@ And here's what it all means, starting from the top...
Several reasons: Several reasons:
* We need to be able to deploy multiple copies of the same helm chart into different namespaces. Imagine if you wanted to deploy a "postgres" helm chart into a namespace for KeyCloak, plus another one for NextCloud. Putting each HelmRelease resource into its own namespace allows us to do this, while sourcing them all from a common HelmRepository * We need to be able to deploy multiple copies of the same helm chart into different namespaces. Imagine if you wanted to deploy a "postgres" helm chart into a namespace for Keycloak, plus another one for NextCloud. Putting each HelmRelease resource into its own namespace allows us to do this, while sourcing them all from a common HelmRepository
* As your cluster grows in complexity, you end up with dependency issues, and sometimes you need one chart deployed first, in order to create CRDs which are depended upon by a second chart (*like Prometheus' ServiceMonitor*). Isolating apps to a kustomization-per-app means you can implement dependencies and health checks to allow a complex cluster design without chicken vs egg problems! * As your cluster grows in complexity, you end up with dependency issues, and sometimes you need one chart deployed first, in order to create CRDs which are depended upon by a second chart (*like Prometheus' ServiceMonitor*). Isolating apps to a kustomization-per-app means you can implement dependencies and health checks to allow a complex cluster design without chicken vs egg problems!
## Got it? ## Got it?

2
manuscript/kubernetes/deployment/flux/operate.md
View File

@@ -30,7 +30,7 @@ We'll need 5 files per-app, to deploy and manage our apps using flux. The exampl
Several reasons: Several reasons:
* We need to be able to deploy multiple copies of the same helm chart into different namespaces. Imagine if you wanted to deploy a "postgres" helm chart into a namespace for KeyCloak, plus another one for NextCloud. Putting each HelmRelease resource into its own namespace allows us to do this, while sourcing them all from a common HelmRepository * We need to be able to deploy multiple copies of the same helm chart into different namespaces. Imagine if you wanted to deploy a "postgres" helm chart into a namespace for Keycloak, plus another one for NextCloud. Putting each HelmRelease resource into its own namespace allows us to do this, while sourcing them all from a common HelmRepository
* As your cluster grows in complexity, you end up with dependency issues, and sometimes you need one chart deployed first, in order to create CRDs which are depended upon by a second chart (*like Prometheus' ServiceMonitor*). Isolating apps to a kustomization-per-app means you can implement dependencies and health checks to allow a complex cluster design without chicken vs egg problems! * As your cluster grows in complexity, you end up with dependency issues, and sometimes you need one chart deployed first, in order to create CRDs which are depended upon by a second chart (*like Prometheus' ServiceMonitor*). Isolating apps to a kustomization-per-app means you can implement dependencies and health checks to allow a complex cluster design without chicken vs egg problems!
* I like to use the one-object-per-yaml-file approach. Kubernetes is complex enough without trying to define multiple objects in one file, or having confusingly-generic filenames such as `app.yaml`! 🤦‍♂️ * I like to use the one-object-per-yaml-file approach. Kubernetes is complex enough without trying to define multiple objects in one file, or having confusingly-generic filenames such as `app.yaml`! 🤦‍♂️

22
manuscript/recipes/keycloak/authenticate-against-openldap.md
View File

@@ -1,20 +1,20 @@
--- ---
title: Integrate LDAP server with Keycloak for user federation 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 !!! 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. 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 ## Ingredients
!!! Summary !!! Summary
Existing: Existing:
* [X] [KeyCloak](/recipes/keycloak/) recipe deployed successfully * [X] [Keycloak](/recipes/keycloak/) recipe deployed successfully
New: New:
@@ -28,11 +28,11 @@ You start in the "Master" realm - but mouseover the realm name, to a dropdown bo
### Create Realm ### Create Realm
![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-1.png){ loading=lazy } ![Keycloak Add Realm Screenshot](/images/sso-stack-keycloak-1.png){ loading=lazy }
Enter a name for your new realm, and click "_Create_": Enter a name for your new realm, and click "_Create_":
![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-2.png){ loading=lazy } ![Keycloak Add Realm Screenshot](/images/sso-stack-keycloak-2.png){ loading=lazy }
### Setup User Federation ### 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: Save your changes, and then navigate back to "User Federation" > Your LDAP name > Mappers:
![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-3.png){ loading=lazy } ![Keycloak Add Realm Screenshot](/images/sso-stack-keycloak-3.png){ 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 * last name
* username * username
* email * email
* first name * first name
![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-4.png){ loading=lazy } ![Keycloak Add Realm Screenshot](/images/sso-stack-keycloak-4.png){ loading=lazy }
## Summary ## 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 !!! Summary
Created: 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" --8<-- "recipe-footer.md"

44
manuscript/recipes/keycloak/create-user.md
View File

@@ -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:
![Navigating to the add user interface in Keycloak](/images/keycloak-add-user-1.png){ loading=lazy }
Populate your new user's username (it's the only mandatory field)
![Populating a username in the add user interface in Keycloak](/images/keycloak-add-user-2.png){ 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!
![Resetting a user's password in Keycloak](/images/keycloak-add-user-3.png){ 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"

72
manuscript/recipes/keycloak/index.md
View File

@@ -1,32 +1,31 @@
--- ---
title: How to setup OIDC server in Docker with KeyCloak title: Run Keycloak behind traefik in Docker
description: Kick-ass OIDC and identity management
--- ---
# 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.
![KeyCloak Screenshot](../../images/keycloak.png){ loading=lazy } ![Keycloak Screenshot](../../images/keycloak.png){ loading=lazy }
--8<-- "recipe-standard-ingredients.md" --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 ```bash
mkdir -p /var/data/runtime/keycloak/database mkdir -p /var/data/runtime/keycloak/database
mkdir -p /var/data/keycloak/database-dump 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 ```bash
# Technically, this could be auto-detected, but we prefer to be prescriptive # Technically, this could be auto-detected, but we prefer to be prescriptive
@@ -59,9 +58,9 @@ BACKUP_NUM_KEEP=7
BACKUP_FREQUENCY=1d 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" --8<-- "premix-cta.md"
@@ -132,14 +131,53 @@ networks:
--8<-- "reference-networks.md" --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`. 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:
![Navigating to the add user interface in Keycloak](/images/keycloak-add-user-1.png){ loading=lazy }
Populate your new user's username (it's the only mandatory field)
![Populating a username in the add user interface in Keycloak](/images/keycloak-add-user-2.png){ 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!
![Resetting a user's password in Keycloak](/images/keycloak-add-user-3.png){ 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" --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!

22
manuscript/recipes/keycloak/setup-oidc-provider.md
View File

@@ -1,20 +1,20 @@
--- ---
title: How to setup OIDC provider 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... 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 !!! 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. 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 ## Ingredients
!!! Summary !!! Summary
Existing: Existing:
* [X] [KeyCloak](/recipes/keycloak/) recipe deployed successfully * [X] [Keycloak](/recipes/keycloak/) recipe deployed successfully
New: 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*): Enter a name for your client (*remember, we're authenticating **applications** now, not users, so use an application-specific name*):
![Adding a client in KeyCloak](/images/keycloak-add-client-2.png){ loading=lazy } ![Adding a client in Keycloak](/images/keycloak-add-client-2.png){ loading=lazy }
### Configure Client ### Configure Client
@@ -39,21 +39,21 @@ Once your client is created, set at **least** the following, and click **Save**
* **Access Type** : Confidential * **Access Type** : Confidential
* **Valid Redirect URIs** : <The URIs you want to protect\> * **Valid Redirect URIs** : <The URIs you want to protect\>
![Set KeyCloak client to confidential access type, add redirect URIs](/images/keycloak-add-client-3.png){ loading=lazy } ![Set Keycloak client to confidential access type, add redirect URIs](/images/keycloak-add-client-3.png){ loading=lazy }
### Retrieve Client Secret ### 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.
![Capture client secret from KeyCloak](/images/keycloak-add-client-4.png){ loading=lazy } ![Capture client secret from Keycloak](/images/keycloak-add-client-4.png){ loading=lazy }
## Summary ## 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 !!! Summary
Created: 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" --8<-- "recipe-footer.md"

8
manuscript/recipes/openldap.md
View File

@@ -21,7 +21,7 @@ This recipe combines the raw power of OpenLDAP with the flexibility and features
## What's the takeaway? ## 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" --8<-- "recipe-standard-ingredients.md"
@@ -377,9 +377,9 @@ networks:
!!! warning !!! 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. **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: 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. 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" --8<-- "recipe-footer.md"

2
manuscript/reference/networks.md
View File

@@ -33,7 +33,7 @@ In order to avoid IP addressing conflicts as we bring swarm networks up/down, we
| [PrivateBin](/recipes/privatebin/) | 172.16.41.0/24 | | [PrivateBin](/recipes/privatebin/) | 172.16.41.0/24 |
| [Wetty](/recipes/wetty/) | 172.16.45.0/24 | | [Wetty](/recipes/wetty/) | 172.16.45.0/24 |
| [phpIPAM](/recipes/phpipam/) | 172.16.47.0/24 | | [phpIPAM](/recipes/phpipam/) | 172.16.47.0/24 |
| [KeyCloak](/recipes/keycloak/) | 172.16.49.0/24 | | [Keycloak](/recipes/keycloak/) | 172.16.49.0/24 |
| [Duplicati](/recipes/duplicati/) | 172.16.55.0/24 | | [Duplicati](/recipes/duplicati/) | 172.16.55.0/24 |
| [Restic](/recipes/restic/) | 172.16.56.0/24 | | [Restic](/recipes/restic/) | 172.16.56.0/24 |
| [Paperless NG](/recipes/paperless-ng/) | 172.16.58.0/24 | | [Paperless NG](/recipes/paperless-ng/) | 172.16.58.0/24 |

11
mkdocs.yml
View File

@@ -56,7 +56,7 @@ nav:
- docker-swarm/traefik-forward-auth/index.md - docker-swarm/traefik-forward-auth/index.md
- Dex (static): docker-swarm/traefik-forward-auth/dex-static.md - Dex (static): docker-swarm/traefik-forward-auth/dex-static.md
- Google: docker-swarm/traefik-forward-auth/google.md - Google: docker-swarm/traefik-forward-auth/google.md
- KeyCloak: docker-swarm/traefik-forward-auth/keycloak.md - Keycloak: docker-swarm/traefik-forward-auth/keycloak.md
- Authelia: docker-swarm/authelia.md - Authelia: docker-swarm/authelia.md
- Registry: docker-swarm/registry.md - Registry: docker-swarm/registry.md
- Mail Server: recipes/mail.md - Mail Server: recipes/mail.md
@@ -85,9 +85,8 @@ nav:
- Huginn: recipes/huginn.md - Huginn: recipes/huginn.md
- Jellyfin: recipes/jellyfin.md - Jellyfin: recipes/jellyfin.md
- Kanboard: recipes/kanboard.md - Kanboard: recipes/kanboard.md
- KeyCloak: - Keycloak:
- recipes/keycloak/index.md - recipes/keycloak/index.md
- Users: recipes/keycloak/create-user.md
- OIDC Provider: recipes/keycloak/setup-oidc-provider.md - OIDC Provider: recipes/keycloak/setup-oidc-provider.md
- OpenLDAP: recipes/keycloak/authenticate-against-openldap.md - OpenLDAP: recipes/keycloak/authenticate-against-openldap.md
- Miniflux: recipes/miniflux.md - Miniflux: recipes/miniflux.md
@@ -114,7 +113,7 @@ nav:
- GitLab Runner: recipes/gitlab-runner.md - GitLab Runner: recipes/gitlab-runner.md
- Gollum: recipes/gollum.md - Gollum: recipes/gollum.md
- InstaPy: recipes/instapy.md - InstaPy: recipes/instapy.md
- KeyCloak: - Keycloak:
- recipes/keycloak/index.md - recipes/keycloak/index.md
- Users: recipes/keycloak/create-user.md - Users: recipes/keycloak/create-user.md
- OIDC Provider: recipes/keycloak/setup-oidc-provider.md - OIDC Provider: recipes/keycloak/setup-oidc-provider.md
@@ -138,7 +137,7 @@ nav:
- docker-swarm/traefik-forward-auth/index.md - docker-swarm/traefik-forward-auth/index.md
- Dex (static): docker-swarm/traefik-forward-auth/dex-static.md - Dex (static): docker-swarm/traefik-forward-auth/dex-static.md
- Google: docker-swarm/traefik-forward-auth/google.md - Google: docker-swarm/traefik-forward-auth/google.md
- KeyCloak: docker-swarm/traefik-forward-auth/keycloak.md - Keycloak: docker-swarm/traefik-forward-auth/keycloak.md
- Wallabag: recipes/wallabag.md - Wallabag: recipes/wallabag.md
- Wekan: recipes/wekan.md - Wekan: recipes/wekan.md
- Wetty: recipes/wetty.md - Wetty: recipes/wetty.md
@@ -213,7 +212,7 @@ nav:
# - Reloader: kubernetes/wip.md # - Reloader: kubernetes/wip.md
# - Dashboard: kubernetes/wip.md # - Dashboard: kubernetes/wip.md
# - Kured: kubernetes/wip.md # - Kured: kubernetes/wip.md
# - KeyCloak: kubernetes/wip.md # - Keycloak: kubernetes/wip.md
# - Recipes: # - Recipes:
# - Harbor: # - Harbor:
# - recipes/kubernetes/harbor/index.md # - recipes/kubernetes/harbor/index.md