diff --git a/docs/_images/user/oauth2-provider/authsource-client-create.png b/docs/_images/user/oauth2-provider/authsource-client-create.png new file mode 100644 index 00000000..004a44b2 Binary files /dev/null and b/docs/_images/user/oauth2-provider/authsource-client-create.png differ diff --git a/docs/_images/user/oauth2-provider/authsource-client-list.png b/docs/_images/user/oauth2-provider/authsource-client-list.png new file mode 100644 index 00000000..40095205 Binary files /dev/null and b/docs/_images/user/oauth2-provider/authsource-client-list.png differ diff --git a/docs/_images/user/oauth2-provider/authsource-intro-login-confirm.png b/docs/_images/user/oauth2-provider/authsource-intro-login-confirm.png new file mode 100644 index 00000000..56d96ed9 Binary files /dev/null and b/docs/_images/user/oauth2-provider/authsource-intro-login-confirm.png differ diff --git a/docs/_images/user/oauth2-provider/authsource-intro-login-create.png b/docs/_images/user/oauth2-provider/authsource-intro-login-create.png new file mode 100644 index 00000000..20792a8b Binary files /dev/null and b/docs/_images/user/oauth2-provider/authsource-intro-login-create.png differ diff --git a/docs/_images/user/oauth2-provider/authsource-intro-login-home.png b/docs/_images/user/oauth2-provider/authsource-intro-login-home.png new file mode 100644 index 00000000..b787aee0 Binary files /dev/null and b/docs/_images/user/oauth2-provider/authsource-intro-login-home.png differ diff --git a/docs/_images/user/oauth2-provider/authsource-intro-login-page.png b/docs/_images/user/oauth2-provider/authsource-intro-login-page.png new file mode 100644 index 00000000..5db96a31 Binary files /dev/null and b/docs/_images/user/oauth2-provider/authsource-intro-login-page.png differ diff --git a/docs/_images/user/oauth2-provider/authsource-provider-create.png b/docs/_images/user/oauth2-provider/authsource-provider-create.png new file mode 100644 index 00000000..e38b36ab Binary files /dev/null and b/docs/_images/user/oauth2-provider/authsource-provider-create.png differ diff --git a/docs/_images/user/oauth2-provider/authsource-provider-show.png b/docs/_images/user/oauth2-provider/authsource-provider-show.png new file mode 100644 index 00000000..779132e1 Binary files /dev/null and b/docs/_images/user/oauth2-provider/authsource-provider-show.png differ diff --git a/docs/admin/oauth2-provider.md b/docs/admin/oauth2-provider.md index 769291c9..be73a459 100644 --- a/docs/admin/oauth2-provider.md +++ b/docs/admin/oauth2-provider.md @@ -3,10 +3,6 @@ title: 'OAuth2 provider' license: 'CC-BY-SA-4.0' --- -Forgejo can act as an instance wide OAuth2 provider. To achieve that, OAuth2 applications must be created in the `/admin/applications` page. - -> **NOTE:** Third party applications obtaining a token for a user via such an application will have administrative rights. OAuth2 scopes are not yet implemented. - ## Pre-registered applications The following OAuth2 applications are pre-registered because it is generally useful for Forgejo to be an OAuth2 provider for the corresponding third party software. Their usage is explained in the [Forgejo user guide](../../user/oauth2-provider/). diff --git a/docs/user/oauth2-provider.md b/docs/user/oauth2-provider.md index 6d0fb3fd..4f40978a 100644 --- a/docs/user/oauth2-provider.md +++ b/docs/user/oauth2-provider.md @@ -6,6 +6,12 @@ origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8 Forgejo supports acting as an OAuth2 provider to allow third party applications to access its resources with the user's consent. +> **NOTE:** scoped tokens or personal access tokens are entirely different from OAuth2, see the [Access Token scope](../token-scope/) section for more information. + +Forgejo can act as an instance wide OAuth2 provider. To achieve that, OAuth2 applications must be created in the `/admin/applications` page. + +> **NOTE:** Third party applications obtaining a token for a user via such an application will have administrative rights. OAuth2 scopes are not yet implemented. + ## Endpoints | Endpoint | URL | @@ -25,10 +31,6 @@ At the moment Forgejo only supports the [**Authorization Code Grant**](https://t 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. To test or debug you can use the web-tool https://oauthdebugger.com/. -## Scoped Tokens - -See the [Access Token scope](../token-scope/) section for more information. - ## 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). @@ -74,6 +76,45 @@ It is possible for any user to manually register a new OAuth2 application in the ## Examples +### Using a Codeberg as an authentication source + +In this example https://v7.next.forgejo.org will be configured to add the option to delegate user registration to https://codeberg.org. + +![Login page with Codeberg authentication source](../_images/user/oauth2-provider/authsource-intro-login-page.png) + +> **NOTE:** in the OAuth2 jargon, https://v7.next.forgejo.org is the OAuth2 client and Codeberg is the OAuth2 provider + +- Choose an arbitrary but distinctive name for the OAuth2 provider: (e.g. **Codeberg**). +- Choose an existing Codeberg user to create the OAuth2 application. It does not need to be a user with elevated privileges. (e.g. **user-for-oauth-application**) +- On https://codeberg.org, login as **user-for-oauth-application** + - Visit https://codeberg.org/user/settings/applications and create a new OAuth2 application. There needs to be only one redirect URI, composed with the abitrary name that was chosen above: https://v7.next.forgejo.org/user/oauth2/Codeberg/callback. + ![Create a new OAuth2 application](../_images/user/oauth2-provider/authsource-provider-create.png) + - When created, the OAuth2 application is given a **Client ID** and a **Client secret** that https://v7.next.forgejo.org will need to let https://codeberg.org know it is an authorized OAuth2 client. + ![Client ID and secret of a new OAuth2 application](../_images/user/oauth2-provider/authsource-provider-show.png) +- On https://v7.next.forgejo.org, login as a user with admin privileges + - Create a new authentication source on https://v7.next.forgejo.org, the Forgejo instance that is going to act as the OAuth2 client, allowing its users to register using the account they have on https://codeberg.org. + - Visit https://v7.next.forgejo.org/admin/auths/new to create the authentication source with: + - **Authentication type:** OAuth2 + - **Authentication name:** the abitrary name that was chosen above (e.g. **Codeberg**) + - **OAuth2 provider:** OpenID Connect + - **Client ID:** copy/pasted from the OAuth2 application created on Codebeg + - **Client Secret:** copy/pasted from the OAuth2 application created on Codebeg + - **Icon URL:** https://design.codeberg.org/logo-kit/icon.svg + - **OpenID Connect Auto Discovery URL:** https://codeberg.org/.well-known/openid-configuration + - Leave all other fields to their default values + ![Create a new OAuth2 authentication soure](../_images/user/oauth2-provider/authsource-client-create.png) + - It will show in the list of authentication sources at https://v7.next.forgejo.org/admin/auths. + ![List of OAuth2 authentication soure](../_images/user/oauth2-provider/authsource-client-list.png) +- On https://v7.next.forgejo.org, not logged in + - Visit https://v7.next.forgejo.org/user/login + ![Login page with Codeberg authentication source](../_images/user/oauth2-provider/authsource-intro-login-page.png) + - Click on **Sign in with Codeberg** to be redirected to Codeberg and authorize https://v7.next.forgejo.org to obtain the details of your account (user name, email, etc.). If you are not already logged in Codeberg, you will need to before this authorization request is presented to you. + ![Authorizing v7.next.forgejo.org](../_images/user/oauth2-provider/authsource-intro-login-confirm.png) + - Review the pre-filled information that will be used to create your account on https://v7.next.forgejo.org. + ![Filling account information](../_images/user/oauth2-provider/authsource-intro-login-create.png) + - You are redirected to the home page of the newly created account. + ![User home page](../_images/user/oauth2-provider/authsource-intro-login-home.png) + ### Confidential client **Note:** This example does not use PKCE.