diff --git a/README.md b/README.md
index ed2af52..2c46c39 100644
--- a/README.md
+++ b/README.md
@@ -79,3 +79,32 @@ app app secret insert git.example.coop signing_public_key v1 -f ~/.ssh/id_ed2551
 app app secret insert git.example.coop signing_private_key v1 -f ~/.ssh/id_ed25519
 app app deploy git.example.coop
 ```
+
+## Keycloak integration
+
+This example uses https://git.coop.tech and https://keycloak.coop.tech as an example. Replace them with your own domains:
+
+### In keycloak
+
+- If you haven't already done so for other services, create a realm.
+- Within that realm, create a client.
+  - Client type = `OpenID Connect`
+  - Client ID = `forgejo`
+  - Client authentication ✅
+  - Authorization ✅
+  - Standard flow ✅
+  - Direct access grants ✅ 
+  - Valid redirect URIs = `https://git.coop.tech/*`
+  - Valid post logout redirect URIs = `https://git.coop.tech/*`
+  - Note the client secret under "clients" -> "credentials"
+
+### In Forgejo
+
+- Go to https://git.coop.tech/admin 
+- Go to "Identity & access"
+- Go to "Authentication sources"
+- Authentication type: `OAuth2`
+- OAuth2 provider: `OpenID Connect`
+- Client ID = `forgejo`
+- Client secret = #see client secret mentioned above
+- OpenID Connect Auto Discovery URL = `https://keycloak.coop.tech/realms/<realm name>/.well-known/openid-configuration`