From b0b4cdf864cd8991ff041968bc5de78f0a41d929 Mon Sep 17 00:00:00 2001
From: techknowlogick <techknowlogick@gitea.com>
Date: Thu, 22 Feb 2024 19:08:17 -0500
Subject: [PATCH] Support SAML authentication (#25165)

Closes https://github.com/go-gitea/gitea/issues/5512

This PR adds basic SAML support
- Adds SAML 2.0 as an auth source
- Adds SAML configuration documentation
- Adds integration test:
- Use bare-bones SAML IdP to test protocol flow and test account is
linked successfully (only runs on Postgres by default)
- Adds documentation for configuring and running SAML integration test
locally

Future PRs:
- Support group mapping
- Support auto-registration (account linking)

Co-Authored-By: @jackHay22

---------

Co-authored-by: jackHay22 <jack@allspice.io>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: KN4CK3R <admin@oldschoolhack.me>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>
Co-authored-by: Jason Song <i@wolfogre.com>
Co-authored-by: morphelinho <morphelinho@users.noreply.github.com>
Co-authored-by: Zettat123 <zettat123@gmail.com>
Co-authored-by: Yarden Shoham <git@yardenshoham.com>
Co-authored-by: 6543 <6543@obermui.de>
Co-authored-by: silverwind <me@silverwind.io>
---
 usage/authentication.en-us.md | 69 +++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/usage/authentication.en-us.md b/usage/authentication.en-us.md
index adc936df..1838cfcc 100644
--- a/usage/authentication.en-us.md
+++ b/usage/authentication.en-us.md
@@ -349,3 +349,72 @@ If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WE
 You can also limit the reverse proxy's IP address range with `REVERSE_PROXY_TRUSTED_PROXIES` which default value is `127.0.0.0/8,::1/128`. By `REVERSE_PROXY_LIMIT`, you can limit trusted proxies level.
 
 Notice: Reverse Proxy Auth doesn't support the API. You still need an access token or basic auth to make API requests.
+
+## SAML
+
+### Configuring Gitea as a SAML 2.0 Service Provider
+
+- Navigate to `Site Administration > Identity & Access > Authentication Sources`.
+- Click the `Add Authentication Source` button.
+- Select `SAML` as the authentication type.
+
+#### Features Not Yet Supported
+
+Currently, auto-registration is not supported for SAML. During the external account linking process the user will be prompted to set a username and email address or link to an existing account.
+
+SAML group mapping is not supported.
+
+#### Settings
+
+- `Authentication Name` **(required)**
+
+  - The name of this authentication source (appears in the Gitea ACS and metadata URLs)
+
+- `SAML NameID Format` **(required)**
+
+  - This specifies how Identity Provider (IdP) users are mapped to Gitea users. This option will be provider specific.
+
+- `Icon URL` (optional)
+
+  - URL of an icon to display on the Sign-In page for this authentication source.
+
+- `[Insecure] Skip Assertion Signature Validation` (optional)
+
+  - This option is not recommended and disables integrity verification of IdP SAML assertions.
+
+- `Identity Provider Metadata URL` (optional if XML set)
+
+  - The URL of the IdP metadata endpoint.
+  - This field must be set if `Identity Provider Metadata XML` is left blank.
+
+- `Identity Provider Metadata XML` (optional if URL set)
+
+  - The XML returned by the IdP metadata endpoint.
+  - This field must be set if `Identity Provider Metadata URL` is left blank.
+
+- `Service Provider Certificate` (optional)
+
+  - X.509-formatted certificate (with `Service Provider Private Key`) used for signing SAML requests.
+  - A certificate will be generated if this field is left blank.
+
+- `Service Provider Private Key` (optional)
+
+  - DSA/RSA private key (with `Service Provider Certificate`) used for signing SAML requests.
+  - A private key will be generated if this field is left blank.
+
+- `Email Assertion Key` (optional)
+
+  - The SAML assertion key used for the IdP user's email (depends on provider configuration).
+
+- `Name Assertion Key` (optional)
+
+  - The SAML assertion key used for the IdP user's nickname (depends on provider configuration).
+
+- `Username Assertion Key` (optional)
+
+  - The SAML assertion key used for the IdP user's username (depends on provider configuration).
+
+### Configuring a SAML 2.0 Identity Provider to use Gitea
+
+- The service provider assertion consumer service url will look like: `http(s)://[mydomain]/user/saml/[Authentication Name]/acs`.
+- The service provider metadata url will look like: `http(s)://[mydomain]/user/saml/[Authentication Name]/metadata`.