diff --git a/manuscript/book.txt b/manuscript/book.txt index b62f082..1c4a4fb 100644 --- a/manuscript/book.txt +++ b/manuscript/book.txt @@ -69,6 +69,9 @@ recipes/gitlab-runner.md recipes/gollum.md recipes/instapy.md recipes/keycloak.md +recipes/keycloak/create-user.md +recipes/keycloak/authenticate-against-openldap.md +recipes/keycloak/setup-oidc-provider.md recipes/openldap.md recipes/mail.md recipes/minio.md diff --git a/manuscript/ha-docker-swarm/traefik-forward-auth.md b/manuscript/ha-docker-swarm/traefik-forward-auth.md index 9809030..498b93a 100644 --- a/manuscript/ha-docker-swarm/traefik-forward-auth.md +++ b/manuscript/ha-docker-swarm/traefik-forward-auth.md @@ -28,7 +28,7 @@ Store your client ID and secret safely - you'll need them for the next step. ### Prepare environment -Create `traefik-forward-auth.env` as follows: +Create `/var/data/config/traefik/traefik-forward-auth.env` as follows: ``` CLIENT_ID= @@ -47,7 +47,7 @@ This is a small container, you can simply add the following content to the exist ``` traefik-forward-auth: image: thomseddon/traefik-forward-auth - env_file: /var/data/config/keycloak/traefik-forward-auth.env + env_file: /var/data/config/traefik/traefik-forward-auth.env networks: - traefik_public # Uncomment these lines if you're using auth host mode @@ -101,10 +101,4 @@ What have we achieved? By adding an additional three simple labels to any servic 1. Traefik forward auth replaces the use of [oauth_proxy containers](/reference/oauth_proxy/) found in some of the existing recipes 2. [@thomaseddon's original version](https://github.com/thomseddon/traefik-forward-auth) of traefik-forward-auth only works with Google currently, but I've created a [fork](https://www.github.com/funkypenguin/traefik-forward-auth) of a [fork](https://github.com/noelcatt/traefik-forward-auth), which implements generic OIDC providers. 3. I reviewed several implementations of forward authenticators for Traefik, but found most to be rather heavy-handed, or specific to a single auth provider. @thomaseddon's go-based docker image is 7MB in size, and with the generic OIDC patch (above), it can be extended to work with any OIDC provider. -4. No, not github natively, but you can ferderate GitHub into KeyCloak, and then use KeyCloak as the OIDC provider. - -### Tip your waiter (support me) 👏 - -Did you receive excellent service? Want to make your waiter happy? (_..and support development of current and future recipes!_) See the [support](/support/) page for (_free or paid)_ ways to say thank you! 👏 - -### Your comments? 💬 \ No newline at end of file +4. No, not github natively, but you can ferderate GitHub into KeyCloak, and then use KeyCloak as the OIDC provider. \ No newline at end of file diff --git a/manuscript/images/keycloak-add-client-1.png b/manuscript/images/keycloak-add-client-1.png new file mode 100644 index 0000000..815fc48 Binary files /dev/null and b/manuscript/images/keycloak-add-client-1.png differ diff --git a/manuscript/images/keycloak-add-client-2.png b/manuscript/images/keycloak-add-client-2.png new file mode 100644 index 0000000..77f9014 Binary files /dev/null and b/manuscript/images/keycloak-add-client-2.png differ diff --git a/manuscript/images/keycloak-add-client-3.png b/manuscript/images/keycloak-add-client-3.png new file mode 100644 index 0000000..23d80f0 Binary files /dev/null and b/manuscript/images/keycloak-add-client-3.png differ diff --git a/manuscript/images/keycloak-add-client-4.png b/manuscript/images/keycloak-add-client-4.png new file mode 100644 index 0000000..06a9c27 Binary files /dev/null and b/manuscript/images/keycloak-add-client-4.png differ diff --git a/manuscript/images/keycloak-add-user-1.png b/manuscript/images/keycloak-add-user-1.png new file mode 100644 index 0000000..d542d37 Binary files /dev/null and b/manuscript/images/keycloak-add-user-1.png differ diff --git a/manuscript/images/keycloak-add-user-2.png b/manuscript/images/keycloak-add-user-2.png new file mode 100644 index 0000000..16e3bf8 Binary files /dev/null and b/manuscript/images/keycloak-add-user-2.png differ diff --git a/manuscript/images/keycloak-add-user-3.png b/manuscript/images/keycloak-add-user-3.png new file mode 100644 index 0000000..b721a29 Binary files /dev/null and b/manuscript/images/keycloak-add-user-3.png differ diff --git a/manuscript/recipes/keycloak.md b/manuscript/recipes/keycloak.md index de8dd3f..0bd88ce 100644 --- a/manuscript/recipes/keycloak.md +++ b/manuscript/recipes/keycloak.md @@ -11,9 +11,12 @@ ## Ingredients -1. [Docker swarm cluster](/ha-docker-swarm/design/) with [persistent shared storage](/ha-docker-swarm/shared-storage-ceph.md) -2. [Traefik](/ha-docker-swarm/traefik_public) configured per design -3. DNS entry for the hostname (_i.e. "keycloak.your-domain.com"_) you intend to use for LDAP Account Manager, pointed to your [keepalived](ha-docker-swarm/keepalived/) IP +!!! Summary + Existing: + + * [X] [Docker swarm cluster](/ha-docker-swarm/design/) with [persistent shared storage](/ha-docker-swarm/shared-storage-ceph.md) + * [X] [Traefik](/ha-docker-swarm/traefik_public) configured per design + * [X] DNS entry for the hostname (_i.e. "keycloak.your-domain.com"_) you intend to use, pointed to your [keepalived](ha-docker-swarm/keepalived/) IP ## Preparation @@ -28,7 +31,7 @@ mkdir -p /var/data/keycloak/database-dump ### Prepare environment -Create ```/var/data/keycloak/keycloak.env```, and populate with the following variables, customized for your own domain structure. +Create `/var/data/keycloak/keycloak.env`, and populate with the following variables, customized for your own domain structure. ``` # Technically, this could be auto-detected, but we prefer to be prescriptive @@ -51,7 +54,7 @@ POSTGRES_USER=keycloak POSTGRES_PASSWORD=myuberpassword ``` -Create /var/data/keycloak/keycloak-backup.env, and populate with the following, so that your database can be backed up to the filesystem, daily: +Create `/var/data/keycloak/keycloak-backup.env`, and populate with the following, so that your database can be backed up to the filesystem, daily: ``` PGHOST=keycloak-db @@ -133,44 +136,7 @@ networks: 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. - -### Integrating into OpenLDAP - -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_). - -You'll need to have completed the [OpenLDAP](/recipes/openldap/) recipe - -You start in the "Master" realm - but mouseover the realm name, to a dropdown box allowing you add an new realm: - -![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-1.png) - -Enter a name for your new realm, and click "_Create_": - -![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-2.png) - -Once in the desired realm, click on **User Federation**, and click **Add Provider**. On the next page ("_Required Settings_"), set the following: - -* **Edit Mode** : Writeable -* **Vendor** : Other -* **Connection URL** : ldap://openldap -* **Users DN** : ou=People, -* **Authentication Type** : simple -* **Bind DN** : cn=admin, -* **Bind Credential** : - -Save your changes, and then navigate back to "User Federation" > Your LDAP name > Mappers: - -![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-3.png) - -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) +Log into your new instance at https://**YOUR-FQDN**, and login with the user/password you defined in `keycloak.env`. !!! important Development of the original KeyCloak recipe is sponsored by [The Common Observatory](https://www.observe.global/). Thanks guys! @@ -178,10 +144,4 @@ For each of the following mappers, click the name, and set the "_Read Only_" fla [![Common Observatory](../images/common_observatory.png)](https://www.observe.global/) -## Chef's Notes - -### Tip your waiter (support me) 👏 - -Did you receive excellent service? Want to make your waiter happy? (_..and support development of current and future recipes!_) See the [support](/support/) page for (_free or paid)_ ways to say thank you! 👏 - -### Your comments? 💬 +## Chef's Notes \ No newline at end of file diff --git a/manuscript/recipes/keycloak/authenticate-against-openldap.md b/manuscript/recipes/keycloak/authenticate-against-openldap.md new file mode 100644 index 0000000..9316628 --- /dev/null +++ b/manuscript/recipes/keycloak/authenticate-against-openldap.md @@ -0,0 +1,66 @@ +# 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](/ha-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 + + New: + + * [ ] An [OpenLDAP server](/recipes/openldap/) (*assuming you want to authenticate against it*) + +## Preparation + +You'll need to have completed the [OpenLDAP](/recipes/openldap/) recipe + +You start in the "Master" realm - but mouseover the realm name, to a dropdown box allowing you add an new realm: + +### Create Realm + +![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-1.png) + +Enter a name for your new realm, and click "_Create_": + +![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-2.png) + +### Setup User Federation + +Once in the desired realm, click on **User Federation**, and click **Add Provider**. On the next page ("_Required Settings_"), set the following: + +* **Edit Mode** : Writeable +* **Vendor** : Other +* **Connection URL** : ldap://openldap +* **Users DN** : ou=People, +* **Authentication Type** : simple +* **Bind DN** : cn=admin, +* **Bind Credential** : + +Save your changes, and then navigate back to "User Federation" > Your LDAP name > Mappers: + +![KeyCloak Add Realm Screenshot](/images/sso-stack-keycloak-3.png) + +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) + + +## 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](/ha-docker-swarm/traefik-forward-auth/). + +!!! Summary + Created: + + * [X] KeyCloak realm in read-write federation with [OpenLDAP](/recipes/openldap/) directory \ No newline at end of file diff --git a/manuscript/recipes/keycloak/create-user.md b/manuscript/recipes/keycloak/create-user.md new file mode 100644 index 0000000..59cf394 --- /dev/null +++ b/manuscript/recipes/keycloak/create-user.md @@ -0,0 +1,35 @@ +# 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/openldap/), below, for example*), you'll want to create some local users.. + +## Ingredients + +!!! Summary + Existing: + + * [X] [KeyCloak](/recipes/keycloak/) recipe deployed successfully + + +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) + +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) + +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) + +## 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/oidc-provider/), potentially to secure vulnerable services using [Traefik Forward Auth](/ha-docker-swarm/traefik-forward-auth/). + +!!! Summary + Created: + + * [X] Username / password to authenticate against [KeyCloak](/recipes/keycloak/) \ No newline at end of file diff --git a/manuscript/recipes/keycloak/setup-oidc-provider.md b/manuscript/recipes/keycloak/setup-oidc-provider.md new file mode 100644 index 0000000..927427a --- /dev/null +++ b/manuscript/recipes/keycloak/setup-oidc-provider.md @@ -0,0 +1,53 @@ +# 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](/recipe/traefik-forward-auth/), we'll setup a client in KeyCloak... + +## Ingredients + +!!! Summary + Existing: + + * [X] [KeyCloak](/recipes/keycloak/) recipe deployed successfully + + New: + + * [ ] The URI(s) to protect with the OIDC provider. Refer to the [Traefik Forward Auth](/recipe/traefik-forward-auth/) recipe for more information + +## Preparation + +### Create Client + +Within the "Master" realm (*no need for more realms yet*), navigate to **Clients**, and then click **Create** at the top right: + +![Navigating to the add user interface in Keycloak](/images/keycloak-add-client-1.png) + +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) + +### Configure Client + +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) + +### 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. + +![Capture client secret from KeyCloak](/images/keycloak-add-client-4.png) + +## Summary + +We've setup an OIDC client in KeyCloak, which we can now use to protect vulnerable services using [Traefik Forward Auth](/ha-docker-swarm/traefik-forward-auth/). The OIDC URL provided by KeyCloak in the master realm, is *https:///auth/realms/master/.well-known/openid-configuration* + +!!! Summary + Created: + + * [X] Client ID and Client Secret used to authenticate against KeyCloak with OpenID Connect \ No newline at end of file diff --git a/manuscript/stylesheets/mailchimp.css b/manuscript/stylesheets/mailchimp.css index 28acd85..63b2824 100644 --- a/manuscript/stylesheets/mailchimp.css +++ b/manuscript/stylesheets/mailchimp.css @@ -22,6 +22,6 @@ font-size: .8rem; transition: background-color .25s cubic-bezier(.1,.7,.1,1),color .25s cubic-bezier(.1,.7,.1,1); } -#mailchimp input[type="seeubmit"]:hover { +#mailchimp input[type="submit"]:hover { color: #F2C94C; } \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index d205808..b2d62b2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,7 +70,11 @@ nav: - iBeacon: recipes/homeassistant/ibeacon.md - Huginn: recipes/huginn.md - Kanboard: recipes/kanboard.md - - KeyCloak: recipes/keycloak.md + - KeyCloak: + - Start: recipes/keycloak.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 - Munin: recipes/munin.md - NextCloud: recipes/nextcloud.md diff --git a/scripts/recipe-footer.md b/scripts/recipe-footer.md index aca1275..aa5a842 100644 --- a/scripts/recipe-footer.md +++ b/scripts/recipe-footer.md @@ -1,8 +1,8 @@ -### Tip your waiter (support me) 👏 +## Tip your waiter (support me) 👏 Did you receive excellent service? Want to make your waiter happy? (_..and support development of current and future recipes!_) See the [support](/support/) page for (_free or paid)_ ways to say thank you! 👏 -### Flirt with waiter (subscribe) 💌 +## Flirt with waiter (subscribe) 💌 Want to know now when this recipe gets updated, or when future recipes are added? Subscribe to the [RSS feed](https://mastodon.social/@geekcookbook_changes.atom), or leave your email address below, and we'll keep you updated. (*double-opt-in, no monkey business, no spam either - check the [archive](https://us16.campaign-archive.com/home/?u=a1d9cee4402be76497a2baf49&id=10e284530a) for proof!*) @@ -25,4 +25,4 @@ Want to know now when this recipe gets updated, or when future recipes are added -### Your comments? 💬 +## Your comments? 💬