public/geek-cookbook
1
0
Fork 0
mirror of https://github.com/funkypenguin/geek-cookbook/ synced 2025-12-23 06:31:49 +00:00
Code Issues Releases Wiki Activity

Experiment with PDF generation

Browse Source 
Signed-off-by: David Young <davidy@funkypenguin.co.nz>
This commit is contained in:
David Young
2022-08-19 16:40:53 +12:00
parent c051e0bdad
commit abf9309cb1
317 changed files with 124 additions and 546 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docs/recipes/keycloak/authenticate-against-openldap.md Normal file
View File

@@ -0,0 +1,71 @@
---
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.
---
# 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][keycloak], and an [OIDC client](/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){ loading=lazy }
Enter a name for your new realm, and click "_Create_":
![Keycloak Add Realm Screenshot](/images/sso-stack-keycloak-2.png){ loading=lazy }
### 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){ 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_)
* last name
* username
* email
* first name
![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/).
!!! Summary
Created:
* [X] Keycloak realm in read-write federation with [OpenLDAP](/recipes/openldap/) directory
--8<-- "recipe-footer.md"

183
docs/recipes/keycloak/index.md Normal file
View File

@@ -0,0 +1,183 @@
---
title: Run Keycloak behind traefik in Docker
---
# 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'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 }
--8<-- "recipe-standard-ingredients.md"
## Setup
### Keycloak 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:
```bash
mkdir -p /var/data/runtime/keycloak/database
mkdir -p /var/data/keycloak/database-dump
```
### Keycloak environment vars
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
DB_VENDOR=postgres
DB_DATABASE=keycloak
DB_ADDR=keycloak-db
DB_USER=keycloak
DB_PASSWORD=myuberpassword
KEYCLOAK_USER=admin
KEYCLOAK_PASSWORD=ilovepasswords
# This is required to run keycloak behind traefik
PROXY_ADDRESS_FORWARDING=true
# What's our hostname?
KEYCLOAK_HOSTNAME=keycloak.example.com
# Tell Postgress what user/password to create
POSTGRES_USER=keycloak
POSTGRES_PASSWORD=myuberpassword
```
Create `/var/data/config/keycloak/keycloak-backup.env`, and populate with the following, so that your database can be backed up to the filesystem, daily:
```bash
PGHOST=keycloak-db
PGUSER=keycloak
PGPASSWORD=myuberpassword
BACKUP_NUM_KEEP=7
BACKUP_FREQUENCY=1d
```
## Docker compose example
Create a Keycloak docker-compose (v3) stack config file, something like this example:
--8<-- "premix-cta.md"
```yaml
version: '3'
services:
keycloak:
image: jboss/keycloak
env_file: /var/data/config/keycloak/keycloak.env
volumes:
- /etc/localtime:/etc/localtime:ro
networks:
- traefik_public
- internal
deploy:
labels:
# traefik
- traefik.enable=true
- traefik.docker.network=traefik_public
# traefikv1
- traefik.frontend.rule=Host:keycloak.example.com
- traefik.port=8080
# traefikv2
- "traefik.http.routers.keycloak.rule=Host(`keycloak.example.com`)"
- "traefik.http.routers.keycloak.entrypoints=https"
- "traefik.http.services.keycloak.loadbalancer.server.port=8080"
keycloak-db:
env_file: /var/data/config/keycloak/keycloak.env
image: postgres:10.1
volumes:
- /var/data/runtime/keycloak/database:/var/lib/postgresql/data
- /etc/localtime:/etc/localtime:ro
networks:
- internal
keycloak-db-backup:
image: postgres:10.1
env_file: /var/data/config/keycloak/keycloak-backup.env
volumes:
- /var/data/keycloak/database-dump:/dump
- /etc/localtime:/etc/localtime:ro
entrypoint: |
bash -c 'bash -s <<EOF
trap "break;exit" SIGHUP SIGINT SIGTERM
sleep 2m
while /bin/true; do
pg_dump -Fc > /dump/dump_\`date +%d-%m-%Y"_"%H_%M_%S\`.psql
(ls -t /dump/dump*.psql|head -n $$BACKUP_NUM_KEEP;ls /dump/dump*.psql)|sort|uniq -u|xargs rm -- {}
sleep $$BACKUP_FREQUENCY
done
EOF'
networks:
- internal
networks:
traefik_public:
external: true
internal:
driver: overlay
ipam:
config:
- subnet: 172.16.49.0/24
```
--8<-- "reference-networks.md"
## Run Keycloak
### Launch Keycloak docker-swarm stack
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`.
### Create Keycloak 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 Keycloak 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
### Keycloak with 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.
### Keycloak 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!

59
docs/recipes/keycloak/setup-oidc-provider.md Normal file
View File

@@ -0,0 +1,59 @@
---
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
!!! 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...
## 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](/docker-swarm/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){ loading=lazy }
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 }
### 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){ 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.
![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://<your-keycloak-url>/realms/master/.well-known/openid-configuration`
!!! Summary
Created:
* [X] Client ID and Client Secret used to authenticate against Keycloak with OpenID Connect
--8<-- "recipe-footer.md"