From 1453ba5d74663b4ab4dcb16006baf04425eb87b4 Mon Sep 17 00:00:00 2001
From: Fabian Kammel <datosh18@gmail.com>
Date: Wed, 29 Jan 2025 06:41:03 +0100
Subject: [PATCH] extend oauth2 examples with gitea (#3351)

* extend oauth2 examples with gitea
* add myself to contributors

---------

Signed-off-by: Fabian Kammel <fabian@kammel.dev>
Co-authored-by: James Hodgkinson <james@terminaloutcomes.com>
---
 CONTRIBUTORS.md                          |  1 +
 book/src/integrations/oauth2/examples.md | 93 ++++++++++++++++++++++++
 2 files changed, 94 insertions(+)

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index 18d677b92..f18c7b93d 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -44,6 +44,7 @@
 - adamcstephens
 - Chris Olstrom (colstrom)
 - Christopher-Robin (cebbinghaus)
+- Fabian Kammel (datosh)
 
 ## Acknowledgements
 
diff --git a/book/src/integrations/oauth2/examples.md b/book/src/integrations/oauth2/examples.md
index b4cf56509..42b3ab4db 100644
--- a/book/src/integrations/oauth2/examples.md
+++ b/book/src/integrations/oauth2/examples.md
@@ -54,6 +54,99 @@ In the virtual host, to protect a location/directory
 </Directory>
 ```
 
+## Gitea
+
+[Gitea](https://docs.gitea.com/) is a painless, self-hosted, all-in-one software
+development service. It has built in support for
+[external authentication](https://docs.gitea.com/administration/authentication)
+including OAuth2.
+
+To set up a Gitea instance to authenticate with Kanidm:
+
+1.  Add an email address to your regular Kanidm account, if it doesn't have one
+    already:
+
+    ```sh
+    kanidm person update your_username -m your_username@example.com
+    ```
+
+2. Create a new Kanidm group for your Gitea users (`gitea_users`), and add your
+    regular account to it:
+
+    ```sh
+    kanidm group create gitea_users
+    kanidm group add-members gitea_users your_username
+    ```
+
+3. Create a new OAuth2 application configuration in Kanidm (`gitea`), configure
+    the redirect URL, and scope access to the `gitea_users` group:
+
+    ```sh
+    kanidm system oauth2 create gitea Gitea https://gitea.example.com/user/login
+    kanidm system oauth2 add-redirect-url gitea https://gitea.example.com/user/oauth2/kanidm/callback
+    kanidm system oauth2 update-scope-map gitea gitea_users email openid profile groups
+    ```
+
+4. Gitea currently [does not support PKCE](https://github.com/go-gitea/gitea/issues/21376)
+    in their OIDC implementation. If you do not perform this step, you will see an error like
+    `No PKCE code challenge was provided with client in enforced PKCE mode.`
+    in your Kanidm server logs. Therefore, we have to disable PKCE for Gitea:
+
+    ```sh
+    kanidm system oauth2 warning-insecure-client-disable-pkce gitea
+    ```
+
+5. Get the `gitea` OAuth2 client secret from Kanidm:
+
+    ```sh
+    kanidm system oauth2 show-basic-secret gitea
+    ```
+
+6. Log in to Gitea with an administrator account and go to Site Administration
+    -> Identity & Access -> Authentication Sources, and "Add Authentication Source",
+    then provide the following details:
+    * **Type**: `OAuth2`
+    * **Name**: `kanidm`, in case you want to choose a different name, make sure
+    to update `kanidm` in the redirect URL in step 3. The full redirect URL is
+    provided at the bottom of the current configuration page in Gitea.
+    * **OAuth2 Provider**: `OpenID Connect`
+    * **Client ID (key)**: `gitea`
+    * **Client Secret**: [from show-basic-secret above]
+    * **OpenID Connect Auto Discovery URL**: `https://kanidm.example.com/oauth2/openid/gitea/.well-known/openid-configuration`
+
+    Alternatively, you can provide the configuration via the CLI:
+
+    ```sh
+    gitea admin auth add-oauth \
+        --provider=openidConnect \
+        --name=kanidm \
+        --key=gitea \
+        --secret=[from show-basic-secret above] \
+        --auto-discover-url=https://kanidm.example.com/oauth2/openid/gitea/.well-known/openid-configuration \
+    ```
+
+You should now see a "Sign in with Kanidm" button on your Gitea login page.
+
+You may additionally want to configure:
+
+*   A Gitea themed icon in Kanidm for the `gitea` OAuth2 application:
+    ```sh
+    curl -LO https://gitea.example.com/assets/img/logo.svg
+    kanidm system oauth2 set-image gitea logo.svg svg
+    rm logo.svg
+    ```
+
+*   To disable password authentication in Gitea, add the following
+    [configuration](https://docs.gitea.com/next/administration/config-cheat-sheet)
+    to `app.ini`:
+
+    ```ini
+    [service]
+    ALLOW_ONLY_EXTERNAL_REGISTRATION = true
+    SHOW_REGISTRATION_BUTTON = false
+    ENABLE_PASSWORD_SIGNIN_FORM = false
+    ```
+
 ## GitLab
 
 [GitLab](https://gitlab.com) is a Git-based software development platform, which