Split keycloak in to mini-recipes in preparation for traefik-forward-auth example

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

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=<your 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? 💬
+4. No, not github natively, but you can ferderate GitHub into KeyCloak, and then use KeyCloak as the OIDC provider.

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 <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.
-
-### 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,<your base DN\>
-* **Authentication Type** : simple
-* **Bind DN** : cn=admin,<your base DN\>
-* **Bind Credential** : <your chosen admin password\>
-
-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

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,<your base DN\>
+* **Authentication Type** : simple
+* **Bind DN** : cn=admin,<your base DN\>
+* **Bind Credential** : <your chosen admin password\>
+
+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

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/)

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** : <The URIs you want to protect\>
+
+![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://<your-keycloak-url\>/auth/realms/master/.well-known/openid-configuration*
+
+!!! Summary
+    Created:
+
+    * [X] Client ID and Client Secret used to authenticate against KeyCloak with OpenID Connect

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;
 }

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

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
 </div>
 <!--End mc_embed_signup-->
 
-### Your comments? 💬
+## Your comments? 💬