Merge pull request 'split the documentation in admin + user + developer' (#120) from earl-warren/website:wip-docs into main

Reviewed-on: https://codeberg.org/forgejo/website/pulls/120

v1.19/admin/index.md

@@ -0,0 +1,13 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'Forgejo v1.19 administrator guide'
+---
+
+* [Configuration Cheat Sheet](config-cheat-sheet)
+* [Upgrade guide](upgrade)
+* [Command Line](command-line)
+* [Reverse Proxy](reverse-proxy)
+* [Email setup](email-setup)
+* [Incoming Email](incoming-email)
+* [Logging Configuration](logging-documentation)
+* [Packages](packages)

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.

v1.19/developer/index.md

@@ -0,0 +1,5 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'Forgejo v1.19 developer guide'
+---
+

v1.19/index.md

@@ -1,18 +1,12 @@
 ---
 layout: '~/layouts/Markdown.astro'
-title: 'Forgejo v1.19 administrator guide'
+title: 'Forgejo v1.19 documentation'
 ---
 
 * [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](authentication)
-* [Email setup](email-setup)
-* [Incoming Email](incoming-email)
-* [Logging Configuration](logging-documentation)
-* [Packages](packages)
-* [API Usage](api-usage)
+* [Administrator guide](admin)
+* [User guide](user)
+* [Developer guide](developer)
 * [License](license)

v1.19/user/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
@@ -274,22 +232,3 @@ configure this, set the fields below:
 
 - 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.

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)

v1.19/user/oauth2-provider.md

@@ -0,0 +1,122 @@
+---
+layout: '~/layouts/Markdown.astro'
+title: 'OAuth2 provider'
+---
+
+Forgejo supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent.
+
+## 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 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.
+
+## Scoped Tokens
+
+Forgejo 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
+
+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).
+
+## 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-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.
+
+   ![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-FORGEJO-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 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](../api-usage) to access the user's resources.