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
@@ -102,9 +102,3 @@ What have we achieved? By adding an additional three simple labels to any servic
 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? 💬

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!
@@ -179,9 +145,3 @@ For each of the following mappers, click the name, and set the "_Read Only_" fla
 
 
 ## 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? 💬

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? 💬