From 1c768eacea754fd15143fd6947e08b8c03dff9c0 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Mon, 27 Feb 2023 21:21:34 +0100 Subject: [PATCH 1/7] docs: add link to the API reference AKA swagger --- v1.19/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/v1.19/index.md b/v1.19/index.md index 4a8d477b..878578e9 100644 --- a/v1.19/index.md +++ b/v1.19/index.md @@ -15,4 +15,5 @@ title: 'Forgejo v1.19 administrator guide' * [Logging Configuration](logging-documentation) * [Packages](packages) * [API Usage](api-usage) +* [API Reference](https://codeberg.org/api/swagger) * [License](license) From 2e2d85f59de7d011c6784f538620e103c5c59d8e Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Tue, 28 Feb 2023 17:40:36 +0100 Subject: [PATCH 2/7] oauth2-provider.md: verbatim copy --- v1.19/oauth2-provider.md | 138 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 v1.19/oauth2-provider.md diff --git a/v1.19/oauth2-provider.md b/v1.19/oauth2-provider.md new file mode 100644 index 00000000..17c12d22 --- /dev/null +++ b/v1.19/oauth2-provider.md @@ -0,0 +1,138 @@ +--- +date: "2019-04-19:44:00+01:00" +title: "OAuth2 provider" +slug: "oauth2-provider" +weight: 41 +toc: false +draft: false +menu: + sidebar: + parent: "developers" + name: "OAuth2 Provider" + weight: 41 + identifier: "oauth2-provider" +--- + +# OAuth2 provider + +**Table of Contents** + +{{< toc >}} + +Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0. + +## Endpoints + +| Endpoint | URL | +| ------------------------ | ----------------------------------- | +| OpenID Connect Discovery | `/.well-known/openid-configuration` | +| Authorization Endpoint | `/login/oauth/authorize` | +| Access Token Endpoint | `/login/oauth/access_token` | +| OpenID Connect UserInfo | `/login/oauth/userinfo` | +| JSON Web Key Set | `/login/oauth/keys` | + +## Supported OAuth2 Grants + +At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the following extensions: + +- [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) +- [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) + +To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings. + +## Scopes + +Gitea supports the following scopes for tokens: + +| Name | Description | +| ---- | ----------- | +| **(no scope)** | Grants read-only access to public user profile and public repositories. | +| **repo** | Full control over all repositories. | +|     **repo:status** | Grants read/write access to commit status in all repositories. | +|     **public_repo** | Grants read/write access to public repositories only. | +| **admin:repo_hook** | Grants access to repository hooks of all repositories. This is included in the `repo` scope. | +|     **write:repo_hook** | Grants read/write access to repository hooks | +|     **read:repo_hook** | Grants read-only access to repository hooks | +| **admin:org** | Grants full access to organization settings | +|     **write:org** | Grants read/write access to organization settings | +|     **read:org** | Grants read-only access to organization settings | +| **admin:public_key** | Grants full access for managing public keys | +|     **write:public_key** | Grant read/write access to public keys | +|     **read:public_key** | Grant read-only access to public keys | +| **admin:org_hook** | Grants full access to organizational-level hooks | +| **notification** | Grants full access to notifications | +| **user** | Grants full access to user profile info | +|     **read:user** | Grants read access to user's profile | +|     **user:email** | Grants read access to user's email addresses | +|     **user:follow** | Grants access to follow/un-follow a user | +| **delete_repo** | Grants access to delete repositories as an admin | +| **package** | Grants full access to hosted packages | +|     **write:package** | Grants read/write access to packages | +|     **read:package** | Grants read access to packages | +|     **delete:package** | Grants delete access to packages | +| **admin:gpg_key** | Grants full access for managing GPG keys | +|     **write:gpg_key** | Grants read/write access to GPG keys | +|     **read:gpg_key** | Grants read-only access to GPG keys | +| **admin:application** | Grants full access to manage applications | +|     **write:application** | Grants read/write access for managing applications | +|     **read:application** | Grants read access for managing applications | +| **sudo** | Allows to perform actions as the site admin. | + +## Client types + +Gitea supports both confidential and public client types, [as defined by RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). + +For public clients, a redirect URI of a loopback IP address such as `http://127.0.0.1/` allows any port. Avoid using `localhost`, [as recommended by RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3). + +## Example + +**Note:** This example does not use PKCE. + +1. Redirect to user to the authorization endpoint in order to get their consent for accessing the resources: + + ```curl + https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE + ``` + + The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks. + + ![Authorization Page](/authorize.png) + + The user will now be asked to authorize your application. If they authorize it, the user will be redirected to the `REDIRECT_URL`, for example: + + ```curl + https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE + ``` + +2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example: + + ```curl + POST https://[YOUR-GITEA-URL]/login/oauth/access_token + ``` + + ```json + { + "client_id": "YOUR_CLIENT_ID", + "client_secret": "YOUR_CLIENT_SECRET", + "code": "RETURNED_CODE", + "grant_type": "authorization_code", + "redirect_uri": "REDIRECT_URI" + } + ``` + + Response: + + ```json + { + "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug", + "token_type": "bearer", + "expires_in": 3600, + "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw" + } + ``` + + The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings. + + The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request. + +3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources. From 22db2662a6260a3c4c026308ef1e52e7bf92f98a Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Tue, 28 Feb 2023 17:43:38 +0100 Subject: [PATCH 3/7] oauth2-provider.md: s/gitea/forgejo/ --- v1.19/oauth2-provider.md | 38 +++++++++++--------------------------- 1 file changed, 11 insertions(+), 27 deletions(-) diff --git a/v1.19/oauth2-provider.md b/v1.19/oauth2-provider.md index 17c12d22..6fce5cce 100644 --- a/v1.19/oauth2-provider.md +++ b/v1.19/oauth2-provider.md @@ -1,25 +1,9 @@ --- -date: "2019-04-19:44:00+01:00" -title: "OAuth2 provider" -slug: "oauth2-provider" -weight: 41 -toc: false -draft: false -menu: - sidebar: - parent: "developers" - name: "OAuth2 Provider" - weight: 41 - identifier: "oauth2-provider" +layout: '~/layouts/Markdown.astro' +title: 'OAuth2 provider' --- -# OAuth2 provider - -**Table of Contents** - -{{< toc >}} - -Gitea supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. This feature is available since release 1.8.0. +Forgejo supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. ## Endpoints @@ -33,16 +17,16 @@ Gitea supports acting as an OAuth2 provider to allow third party applications to ## Supported OAuth2 Grants -At the moment Gitea only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the following extensions: +At the moment Forgejo only supports the [**Authorization Code Grant**](https://tools.ietf.org/html/rfc6749#section-1.3.1) standard with additional support of the following extensions: - [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) - [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) To use the Authorization Code Grant as a third party application it is required to register a new application via the "Settings" (`/user/settings/applications`) section of the settings. -## Scopes +## Scoped Tokens -Gitea supports the following scopes for tokens: +Forgejo supports the following scopes for tokens: | Name | Description | | ---- | ----------- | @@ -80,7 +64,7 @@ Gitea supports the following scopes for tokens: ## Client types -Gitea supports both confidential and public client types, [as defined by RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). +Forgejo supports both confidential and public client types, [as defined by RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). For public clients, a redirect URI of a loopback IP address such as `http://127.0.0.1/` allows any port. Avoid using `localhost`, [as recommended by RFC 8252](https://datatracker.ietf.org/doc/html/rfc8252#section-8.3). @@ -91,7 +75,7 @@ For public clients, a redirect URI of a loopback IP address such as `http://127. 1. Redirect to user to the authorization endpoint in order to get their consent for accessing the resources: ```curl - https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE + https://[YOUR-FORGEJO-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI& response_type=code&state=STATE ``` The `CLIENT_ID` can be obtained by registering an application in the settings. The `STATE` is a random string that will be send back to your application after the user authorizes. The `state` parameter is optional but should be used to prevent CSRF attacks. @@ -107,7 +91,7 @@ For public clients, a redirect URI of a loopback IP address such as `http://127. 2. Using the provided `code` from the redirect, you can request a new application and refresh token. The access token endpoints accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example: ```curl - POST https://[YOUR-GITEA-URL]/login/oauth/access_token + POST https://[YOUR-FORGEJO-URL]/login/oauth/access_token ``` ```json @@ -131,8 +115,8 @@ For public clients, a redirect URI of a loopback IP address such as `http://127. } ``` - The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Gitea and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings. + The `CLIENT_SECRET` is the unique secret code generated for this application. Please note that the secret will only be visible after you created/registered the application with Forgejo and cannot be recovered. If you lose the secret you must regenerate the secret via the application's settings. The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request. -3. Use the `access_token` to make [API requests](https://docs.gitea.io/en-us/api-usage#oauth2) to access the user's resources. +3. Use the `access_token` to make [API requests](../api-usage) to access the user's resources. From c3b1fe0334d7361051486ea81f68f471693f21dd Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Tue, 28 Feb 2023 17:44:51 +0100 Subject: [PATCH 4/7] authentication.md: does not belong, it is in the config sheet --- v1.19/authentication.md | 42 ----------------------------------------- 1 file changed, 42 deletions(-) diff --git a/v1.19/authentication.md b/v1.19/authentication.md index 60ffa86e..b495f68a 100644 --- a/v1.19/authentication.md +++ b/v1.19/authentication.md @@ -194,48 +194,6 @@ Debian including Ubuntu and Mint, consult your distribution's documentation. [^2]: **This is a required field for PAM**. Be aware: In the above example, the user will log into the Forgejo web interface as `gituser` and not `gituser@mail.com` -## SMTP (Simple Mail Transfer Protocol) - -This option allows Forgejo to log in to an SMTP host as a Forgejo user. To -configure this, set the fields below: - -- Authentication Name **(required)** - - - A name to assign to the new method of authorization. - -- SMTP Authentication Type **(required)** - - - Type of authentication to use to connect to SMTP host, PLAIN or LOGIN. - -- Host **(required)** - - - The address where the SMTP host can be reached. - - Example: `smtp.mydomain.com` - -- Port **(required)** - - - The port to use when connecting to the server. - - Example: `587` - -- Allowed Domains - - - Restrict what domains can log in if using a public SMTP host or SMTP host - with multiple domains. - - Example: `forgejo.org,mydomain.com,mydomain2.com` - -- Force SMTPS - - - SMTPS will be used by default for connections to port 465, if you wish to use SMTPS - for other ports. Set this value. - - Otherwise if the server provides the `STARTTLS` extension this will be used. - -- Skip TLS Verify - - - Disable TLS verify on authentication. - -- This Authentication Source is Activated - - Enable or disable this authentication source. - ## FreeIPA - In order to log in to Forgejo using FreeIPA credentials, a bind account needs to From 9466cebdaacaf0b19b75269f89cd3d2c34e41e0a Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Tue, 28 Feb 2023 17:45:21 +0100 Subject: [PATCH 5/7] index.md: group authentication & oauth2-provider --- v1.19/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/v1.19/index.md b/v1.19/index.md index 878578e9..eb902511 100644 --- a/v1.19/index.md +++ b/v1.19/index.md @@ -9,7 +9,9 @@ title: 'Forgejo v1.19 administrator guide' * [Configuration Cheat Sheet](config-cheat-sheet) * [Upgrade guide](upgrade) * [Command Line](command-line) -* [Authentication](authentication) +* Authentication + * [LDAP, PAM, FreeIPA, Reverse Proxy](authentication) + * [OAuth2, Scoped Tokens, Client Types](oauth2-provider) * [Email setup](email-setup) * [Incoming Email](incoming-email) * [Logging Configuration](logging-documentation) From 04548024125e6ff31266e9161edc3da1ab013134 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Wed, 1 Mar 2023 18:46:37 +0100 Subject: [PATCH 6/7] move admin guide down one level --- v1.19/{ => admin}/api-usage.md | 0 v1.19/{ => admin}/authentication.md | 0 v1.19/{ => admin}/command-line.md | 0 v1.19/{ => admin}/config-cheat-sheet.md | 0 v1.19/{ => admin}/email-setup.md | 0 v1.19/{ => admin}/incoming-email.md | 0 v1.19/{ => admin}/index.md | 0 v1.19/{ => admin}/license.md | 0 v1.19/{ => admin}/logging-documentation.md | 0 v1.19/{ => admin}/oauth2-provider.md | 0 v1.19/{ => admin}/packages/cargo.md | 0 v1.19/{ => admin}/packages/chef.md | 0 v1.19/{ => admin}/packages/composer.md | 0 v1.19/{ => admin}/packages/conan.md | 0 v1.19/{ => admin}/packages/conda.md | 0 v1.19/{ => admin}/packages/container.md | 0 v1.19/{ => admin}/packages/generic.md | 0 v1.19/{ => admin}/packages/helm.md | 0 v1.19/{ => admin}/packages/index.md | 0 v1.19/{ => admin}/packages/maven.md | 0 v1.19/{ => admin}/packages/npm.md | 0 v1.19/{ => admin}/packages/nuget.md | 0 v1.19/{ => admin}/packages/pub.md | 0 v1.19/{ => admin}/packages/pypi.md | 0 v1.19/{ => admin}/packages/rubygems.md | 0 v1.19/{ => admin}/packages/storage.md | 0 v1.19/{ => admin}/packages/vagrant.md | 0 v1.19/{ => admin}/upgrade.md | 0 28 files changed, 0 insertions(+), 0 deletions(-) rename v1.19/{ => admin}/api-usage.md (100%) rename v1.19/{ => admin}/authentication.md (100%) rename v1.19/{ => admin}/command-line.md (100%) rename v1.19/{ => admin}/config-cheat-sheet.md (100%) rename v1.19/{ => admin}/email-setup.md (100%) rename v1.19/{ => admin}/incoming-email.md (100%) rename v1.19/{ => admin}/index.md (100%) rename v1.19/{ => admin}/license.md (100%) rename v1.19/{ => admin}/logging-documentation.md (100%) rename v1.19/{ => admin}/oauth2-provider.md (100%) rename v1.19/{ => admin}/packages/cargo.md (100%) rename v1.19/{ => admin}/packages/chef.md (100%) rename v1.19/{ => admin}/packages/composer.md (100%) rename v1.19/{ => admin}/packages/conan.md (100%) rename v1.19/{ => admin}/packages/conda.md (100%) rename v1.19/{ => admin}/packages/container.md (100%) rename v1.19/{ => admin}/packages/generic.md (100%) rename v1.19/{ => admin}/packages/helm.md (100%) rename v1.19/{ => admin}/packages/index.md (100%) rename v1.19/{ => admin}/packages/maven.md (100%) rename v1.19/{ => admin}/packages/npm.md (100%) rename v1.19/{ => admin}/packages/nuget.md (100%) rename v1.19/{ => admin}/packages/pub.md (100%) rename v1.19/{ => admin}/packages/pypi.md (100%) rename v1.19/{ => admin}/packages/rubygems.md (100%) rename v1.19/{ => admin}/packages/storage.md (100%) rename v1.19/{ => admin}/packages/vagrant.md (100%) rename v1.19/{ => admin}/upgrade.md (100%) diff --git a/v1.19/api-usage.md b/v1.19/admin/api-usage.md similarity index 100% rename from v1.19/api-usage.md rename to v1.19/admin/api-usage.md diff --git a/v1.19/authentication.md b/v1.19/admin/authentication.md similarity index 100% rename from v1.19/authentication.md rename to v1.19/admin/authentication.md diff --git a/v1.19/command-line.md b/v1.19/admin/command-line.md similarity index 100% rename from v1.19/command-line.md rename to v1.19/admin/command-line.md diff --git a/v1.19/config-cheat-sheet.md b/v1.19/admin/config-cheat-sheet.md similarity index 100% rename from v1.19/config-cheat-sheet.md rename to v1.19/admin/config-cheat-sheet.md diff --git a/v1.19/email-setup.md b/v1.19/admin/email-setup.md similarity index 100% rename from v1.19/email-setup.md rename to v1.19/admin/email-setup.md diff --git a/v1.19/incoming-email.md b/v1.19/admin/incoming-email.md similarity index 100% rename from v1.19/incoming-email.md rename to v1.19/admin/incoming-email.md diff --git a/v1.19/index.md b/v1.19/admin/index.md similarity index 100% rename from v1.19/index.md rename to v1.19/admin/index.md diff --git a/v1.19/license.md b/v1.19/admin/license.md similarity index 100% rename from v1.19/license.md rename to v1.19/admin/license.md diff --git a/v1.19/logging-documentation.md b/v1.19/admin/logging-documentation.md similarity index 100% rename from v1.19/logging-documentation.md rename to v1.19/admin/logging-documentation.md diff --git a/v1.19/oauth2-provider.md b/v1.19/admin/oauth2-provider.md similarity index 100% rename from v1.19/oauth2-provider.md rename to v1.19/admin/oauth2-provider.md diff --git a/v1.19/packages/cargo.md b/v1.19/admin/packages/cargo.md similarity index 100% rename from v1.19/packages/cargo.md rename to v1.19/admin/packages/cargo.md diff --git a/v1.19/packages/chef.md b/v1.19/admin/packages/chef.md similarity index 100% rename from v1.19/packages/chef.md rename to v1.19/admin/packages/chef.md diff --git a/v1.19/packages/composer.md b/v1.19/admin/packages/composer.md similarity index 100% rename from v1.19/packages/composer.md rename to v1.19/admin/packages/composer.md diff --git a/v1.19/packages/conan.md b/v1.19/admin/packages/conan.md similarity index 100% rename from v1.19/packages/conan.md rename to v1.19/admin/packages/conan.md diff --git a/v1.19/packages/conda.md b/v1.19/admin/packages/conda.md similarity index 100% rename from v1.19/packages/conda.md rename to v1.19/admin/packages/conda.md diff --git a/v1.19/packages/container.md b/v1.19/admin/packages/container.md similarity index 100% rename from v1.19/packages/container.md rename to v1.19/admin/packages/container.md diff --git a/v1.19/packages/generic.md b/v1.19/admin/packages/generic.md similarity index 100% rename from v1.19/packages/generic.md rename to v1.19/admin/packages/generic.md diff --git a/v1.19/packages/helm.md b/v1.19/admin/packages/helm.md similarity index 100% rename from v1.19/packages/helm.md rename to v1.19/admin/packages/helm.md diff --git a/v1.19/packages/index.md b/v1.19/admin/packages/index.md similarity index 100% rename from v1.19/packages/index.md rename to v1.19/admin/packages/index.md diff --git a/v1.19/packages/maven.md b/v1.19/admin/packages/maven.md similarity index 100% rename from v1.19/packages/maven.md rename to v1.19/admin/packages/maven.md diff --git a/v1.19/packages/npm.md b/v1.19/admin/packages/npm.md similarity index 100% rename from v1.19/packages/npm.md rename to v1.19/admin/packages/npm.md diff --git a/v1.19/packages/nuget.md b/v1.19/admin/packages/nuget.md similarity index 100% rename from v1.19/packages/nuget.md rename to v1.19/admin/packages/nuget.md diff --git a/v1.19/packages/pub.md b/v1.19/admin/packages/pub.md similarity index 100% rename from v1.19/packages/pub.md rename to v1.19/admin/packages/pub.md diff --git a/v1.19/packages/pypi.md b/v1.19/admin/packages/pypi.md similarity index 100% rename from v1.19/packages/pypi.md rename to v1.19/admin/packages/pypi.md diff --git a/v1.19/packages/rubygems.md b/v1.19/admin/packages/rubygems.md similarity index 100% rename from v1.19/packages/rubygems.md rename to v1.19/admin/packages/rubygems.md diff --git a/v1.19/packages/storage.md b/v1.19/admin/packages/storage.md similarity index 100% rename from v1.19/packages/storage.md rename to v1.19/admin/packages/storage.md diff --git a/v1.19/packages/vagrant.md b/v1.19/admin/packages/vagrant.md similarity index 100% rename from v1.19/packages/vagrant.md rename to v1.19/admin/packages/vagrant.md diff --git a/v1.19/upgrade.md b/v1.19/admin/upgrade.md similarity index 100% rename from v1.19/upgrade.md rename to v1.19/admin/upgrade.md From 41b0111c5972142be85bd6080129f3202428a168 Mon Sep 17 00:00:00 2001 From: Earl Warren Date: Wed, 1 Mar 2023 18:47:26 +0100 Subject: [PATCH 7/7] split the documentation into user/developer/admin --- v1.19/admin/index.md | 10 +--------- v1.19/admin/reverse-proxy.md | 21 +++++++++++++++++++++ v1.19/developer/index.md | 5 +++++ v1.19/index.md | 12 ++++++++++++ v1.19/{admin => }/license.md | 0 v1.19/{admin => user}/api-usage.md | 0 v1.19/{admin => user}/authentication.md | 19 ------------------- v1.19/user/index.md | 10 ++++++++++ v1.19/{admin => user}/oauth2-provider.md | 0 9 files changed, 49 insertions(+), 28 deletions(-) create mode 100644 v1.19/admin/reverse-proxy.md create mode 100644 v1.19/developer/index.md create mode 100644 v1.19/index.md rename v1.19/{admin => }/license.md (100%) rename v1.19/{admin => user}/api-usage.md (100%) rename v1.19/{admin => user}/authentication.md (87%) create mode 100644 v1.19/user/index.md rename v1.19/{admin => user}/oauth2-provider.md (100%) diff --git a/v1.19/admin/index.md b/v1.19/admin/index.md index eb902511..496e4390 100644 --- a/v1.19/admin/index.md +++ b/v1.19/admin/index.md @@ -3,19 +3,11 @@ layout: '~/layouts/Markdown.astro' title: 'Forgejo v1.19 administrator guide' --- -* [What is Forgejo?](https://forgejo.org/) -* [Installation](https://forgejo.org/download/) -* [FAQ](https://forgejo.org/faq/) * [Configuration Cheat Sheet](config-cheat-sheet) * [Upgrade guide](upgrade) * [Command Line](command-line) -* Authentication - * [LDAP, PAM, FreeIPA, Reverse Proxy](authentication) - * [OAuth2, Scoped Tokens, Client Types](oauth2-provider) +* [Reverse Proxy](reverse-proxy) * [Email setup](email-setup) * [Incoming Email](incoming-email) * [Logging Configuration](logging-documentation) * [Packages](packages) -* [API Usage](api-usage) -* [API Reference](https://codeberg.org/api/swagger) -* [License](license) diff --git a/v1.19/admin/reverse-proxy.md b/v1.19/admin/reverse-proxy.md new file mode 100644 index 00000000..59ae317c --- /dev/null +++ b/v1.19/admin/reverse-proxy.md @@ -0,0 +1,21 @@ +--- +layout: '~/layouts/Markdown.astro' +title: 'Reverse proxy' +--- + +Forgejo supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with + +```ini +[service] +ENABLE_REVERSE_PROXY_AUTHENTICATION = true +``` + +The default login user name is in the `X-WEBAUTH-USER` header, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_USER` in app.ini. If the user doesn't exist, you can enable automatic registration with `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true`. + +The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_EMAIL` in app.ini, this could also be disabled with `ENABLE_REVERSE_PROXY_EMAIL` + +If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`. + +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. diff --git a/v1.19/developer/index.md b/v1.19/developer/index.md new file mode 100644 index 00000000..4795263d --- /dev/null +++ b/v1.19/developer/index.md @@ -0,0 +1,5 @@ +--- +layout: '~/layouts/Markdown.astro' +title: 'Forgejo v1.19 developer guide' +--- + diff --git a/v1.19/index.md b/v1.19/index.md new file mode 100644 index 00000000..52128d68 --- /dev/null +++ b/v1.19/index.md @@ -0,0 +1,12 @@ +--- +layout: '~/layouts/Markdown.astro' +title: 'Forgejo v1.19 documentation' +--- + +* [What is Forgejo?](https://forgejo.org/) +* [Installation](https://forgejo.org/download/) +* [FAQ](https://forgejo.org/faq/) +* [Administrator guide](admin) +* [User guide](user) +* [Developer guide](developer) +* [License](license) diff --git a/v1.19/admin/license.md b/v1.19/license.md similarity index 100% rename from v1.19/admin/license.md rename to v1.19/license.md diff --git a/v1.19/admin/api-usage.md b/v1.19/user/api-usage.md similarity index 100% rename from v1.19/admin/api-usage.md rename to v1.19/user/api-usage.md diff --git a/v1.19/admin/authentication.md b/v1.19/user/authentication.md similarity index 87% rename from v1.19/admin/authentication.md rename to v1.19/user/authentication.md index b495f68a..ae738318 100644 --- a/v1.19/admin/authentication.md +++ b/v1.19/user/authentication.md @@ -232,22 +232,3 @@ user will log into the Forgejo web interface as `gituser` and not `gituser@mail. - Log in to Forgejo as an Administrator and click on "Authentication" under Admin Panel. Then click `Add New Source` and fill in the details, changing all where appropriate. - -## Reverse Proxy - -Forgejo supports Reverse Proxy Header authentication, it will read headers as a trusted login user name or user email address. This hasn't been enabled by default, you can enable it with - -```ini -[service] -ENABLE_REVERSE_PROXY_AUTHENTICATION = true -``` - -The default login user name is in the `X-WEBAUTH-USER` header, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_USER` in app.ini. If the user doesn't exist, you can enable automatic registration with `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION=true`. - -The default login user email is `X-WEBAUTH-EMAIL`, you can change it via changing `REVERSE_PROXY_AUTHENTICATION_EMAIL` in app.ini, this could also be disabled with `ENABLE_REVERSE_PROXY_EMAIL` - -If set `ENABLE_REVERSE_PROXY_FULL_NAME=true`, a user full name expected in `X-WEBAUTH-FULLNAME` will be assigned to the user when auto creating the user. You can also change the header name with `REVERSE_PROXY_AUTHENTICATION_FULL_NAME`. - -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. diff --git a/v1.19/user/index.md b/v1.19/user/index.md new file mode 100644 index 00000000..8bd0f0ff --- /dev/null +++ b/v1.19/user/index.md @@ -0,0 +1,10 @@ +--- +layout: '~/layouts/Markdown.astro' +title: 'Forgejo v1.19 user guide' +--- + +* Authentication + * [LDAP, PAM, FreeIPA](authentication) + * [OAuth2, Scoped Tokens, Client Types](oauth2-provider) +* [API Usage](api-usage) +* [API Reference](https://codeberg.org/api/swagger) diff --git a/v1.19/admin/oauth2-provider.md b/v1.19/user/oauth2-provider.md similarity index 100% rename from v1.19/admin/oauth2-provider.md rename to v1.19/user/oauth2-provider.md