From 45f499c221134875fdf5cb12d6a1278ed1f88bf1 Mon Sep 17 00:00:00 2001 From: David Young Date: Tue, 12 Jul 2022 16:00:01 +1200 Subject: [PATCH] Improve Keycloak recipe Signed-off-by: David Young --- _snippets/recipe-standard-ingredients.md | 2 +- manuscript/CHANGELOG.md | 2 +- .../traefik-forward-auth/dex-static.md | 2 +- .../traefik-forward-auth/index.md | 6 +- .../traefik-forward-auth/keycloak.md | 12 ++-- manuscript/kubernetes/cluster/index.md | 2 +- .../kubernetes/deployment/flux/design.md | 2 +- .../kubernetes/deployment/flux/operate.md | 2 +- .../keycloak/authenticate-against-openldap.md | 22 +++--- manuscript/recipes/keycloak/create-user.md | 44 ------------ manuscript/recipes/keycloak/index.md | 72 ++++++++++++++----- .../recipes/keycloak/setup-oidc-provider.md | 22 +++--- manuscript/recipes/openldap.md | 8 +-- manuscript/reference/networks.md | 2 +- mkdocs.yml | 11 ++- 15 files changed, 102 insertions(+), 109 deletions(-) delete mode 100644 manuscript/recipes/keycloak/create-user.md diff --git a/_snippets/recipe-standard-ingredients.md b/_snippets/recipe-standard-ingredients.md index 54e10a4..b0cb476 100644 --- a/_snippets/recipe-standard-ingredients.md +++ b/_snippets/recipe-standard-ingredients.md @@ -1,4 +1,4 @@ -## Ingredients +## Requirements !!! summary "Ingredients" Already deployed: diff --git a/manuscript/CHANGELOG.md b/manuscript/CHANGELOG.md index 2b780f8..90ce421 100644 --- a/manuscript/CHANGELOG.md +++ b/manuscript/CHANGELOG.md @@ -21,7 +21,7 @@ Recipe | Description Recipe | Description | Date ----------------------------|---------------------------------------------------------------------------------|-------------- [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_ [Portainer][portainer] | Bump to version 2, bringing "expert simplicity" to your Docker stack management | _25 Jan 2021_ diff --git a/manuscript/docker-swarm/traefik-forward-auth/dex-static.md b/manuscript/docker-swarm/traefik-forward-auth/dex-static.md index d31d694..3092085 100644 --- a/manuscript/docker-swarm/traefik-forward-auth/dex-static.md +++ b/manuscript/docker-swarm/traefik-forward-auth/dex-static.md @@ -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](/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" diff --git a/manuscript/docker-swarm/traefik-forward-auth/index.md b/manuscript/docker-swarm/traefik-forward-auth/index.md index 8c5feb2..b37c120 100644 --- a/manuscript/docker-swarm/traefik-forward-auth/index.md +++ b/manuscript/docker-swarm/traefik-forward-auth/index.md @@ -46,12 +46,12 @@ This clever workaround only works under 2 conditions: ## 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 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" -[^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. diff --git a/manuscript/docker-swarm/traefik-forward-auth/keycloak.md b/manuscript/docker-swarm/traefik-forward-auth/keycloak.md index 1e8c7a9..018d20e 100644 --- a/manuscript/docker-swarm/traefik-forward-auth/keycloak.md +++ b/manuscript/docker-swarm/traefik-forward-auth/keycloak.md @@ -2,9 +2,9 @@ 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. --- -# 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" 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 -Browse to (_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 (_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 @@ -87,13 +87,13 @@ And re-deploy your services :) ## 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" 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" diff --git a/manuscript/kubernetes/cluster/index.md b/manuscript/kubernetes/cluster/index.md index 84a90f9..fec1089 100644 --- a/manuscript/kubernetes/cluster/index.md +++ b/manuscript/kubernetes/cluster/index.md @@ -34,7 +34,7 @@ Cloud providers make it easy to connect their storage solutions to your cluster, ### 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 diff --git a/manuscript/kubernetes/deployment/flux/design.md b/manuscript/kubernetes/deployment/flux/design.md index ee9615e..6301cae 100644 --- a/manuscript/kubernetes/deployment/flux/design.md +++ b/manuscript/kubernetes/deployment/flux/design.md @@ -53,7 +53,7 @@ And here's what it all means, starting from the top... 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! ## Got it? diff --git a/manuscript/kubernetes/deployment/flux/operate.md b/manuscript/kubernetes/deployment/flux/operate.md index 0a60f07..679bc8b 100644 --- a/manuscript/kubernetes/deployment/flux/operate.md +++ b/manuscript/kubernetes/deployment/flux/operate.md @@ -30,7 +30,7 @@ We'll need 5 files per-app, to deploy and manage our apps using flux. The exampl 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! * 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`! 🤦‍♂️ diff --git a/manuscript/recipes/keycloak/authenticate-against-openldap.md b/manuscript/recipes/keycloak/authenticate-against-openldap.md index 1ff3c7d..9664ce5 100644 --- a/manuscript/recipes/keycloak/authenticate-against-openldap.md +++ b/manuscript/recipes/keycloak/authenticate-against-openldap.md @@ -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 -![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_": -![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 @@ -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: -![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 * username * email * 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 -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" diff --git a/manuscript/recipes/keycloak/create-user.md b/manuscript/recipes/keycloak/create-user.md deleted file mode 100644 index 931b5ab..0000000 --- a/manuscript/recipes/keycloak/create-user.md +++ /dev/null @@ -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" diff --git a/manuscript/recipes/keycloak/index.md b/manuscript/recipes/keycloak/index.md index e766b74..59f4ff8 100644 --- a/manuscript/recipes/keycloak/index.md +++ b/manuscript/recipes/keycloak/index.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. -![KeyCloak Screenshot](../../images/keycloak.png){ loading=lazy } +![Keycloak Screenshot](../../images/keycloak.png){ 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 ` +Launch the Keycloak stack by running `docker stack deploy keycloak -c ` 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" -[^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! diff --git a/manuscript/recipes/keycloak/setup-oidc-provider.md b/manuscript/recipes/keycloak/setup-oidc-provider.md index 6693bff..9f86b49 100644 --- a/manuscript/recipes/keycloak/setup-oidc-provider.md +++ b/manuscript/recipes/keycloak/setup-oidc-provider.md @@ -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*): -![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 @@ -39,21 +39,21 @@ Once your client is created, set at **least** the following, and click **Save** * **Access Type** : Confidential * **Valid Redirect URIs** : -![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 -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 -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:///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:///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" diff --git a/manuscript/recipes/openldap.md b/manuscript/recipes/openldap.md index 8de8217..a10d53c 100644 --- a/manuscript/recipes/openldap.md +++ b/manuscript/recipes/openldap.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 _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" diff --git a/manuscript/reference/networks.md b/manuscript/reference/networks.md index bfa2c5d..4e801dc 100644 --- a/manuscript/reference/networks.md +++ b/manuscript/reference/networks.md @@ -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 | | [Wetty](/recipes/wetty/) | 172.16.45.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 | | [Restic](/recipes/restic/) | 172.16.56.0/24 | | [Paperless NG](/recipes/paperless-ng/) | 172.16.58.0/24 | diff --git a/mkdocs.yml b/mkdocs.yml index 9b6868a..75ed6b5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,7 +56,7 @@ nav: - docker-swarm/traefik-forward-auth/index.md - Dex (static): docker-swarm/traefik-forward-auth/dex-static.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 - Registry: docker-swarm/registry.md - Mail Server: recipes/mail.md @@ -85,9 +85,8 @@ nav: - Huginn: recipes/huginn.md - Jellyfin: recipes/jellyfin.md - Kanboard: recipes/kanboard.md - - KeyCloak: + - Keycloak: - recipes/keycloak/index.md - - Users: recipes/keycloak/create-user.md - OIDC Provider: recipes/keycloak/setup-oidc-provider.md - OpenLDAP: recipes/keycloak/authenticate-against-openldap.md - Miniflux: recipes/miniflux.md @@ -114,7 +113,7 @@ nav: - GitLab Runner: recipes/gitlab-runner.md - Gollum: recipes/gollum.md - InstaPy: recipes/instapy.md - - KeyCloak: + - Keycloak: - recipes/keycloak/index.md - Users: recipes/keycloak/create-user.md - OIDC Provider: recipes/keycloak/setup-oidc-provider.md @@ -138,7 +137,7 @@ nav: - docker-swarm/traefik-forward-auth/index.md - Dex (static): docker-swarm/traefik-forward-auth/dex-static.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 - Wekan: recipes/wekan.md - Wetty: recipes/wetty.md @@ -213,7 +212,7 @@ nav: # - Reloader: kubernetes/wip.md # - Dashboard: kubernetes/wip.md # - Kured: kubernetes/wip.md - # - KeyCloak: kubernetes/wip.md + # - Keycloak: kubernetes/wip.md # - Recipes: # - Harbor: # - recipes/kubernetes/harbor/index.md