forgejo-docs/docs/user/oauth2-provider.md at e2728166f6d88113a96117144095c68b4eb2999d

mirror of https://codeberg.org/forgejo/docs.git synced 2024-12-01 19:17:12 -05:00

Earl Warren e2728166f6 {user,admin}: oauth2-provider: pre-registered OAuth applications

(cherry picked from commit be5b8993c9)

2023-11-19 18:09:34 +00:00

9.7 KiB

Raw Blame History

title	license	origin_url
OAuth2 provider	Apache-2.0	`abe8fe3527/docs/content/development/oauth2-provider.en-us.md`

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 standard with additional support of the following extensions:

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 section for more information.

Client types

Forgejo supports both confidential and public client types, as defined by RFC 6749.

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.

Git authentication

OAuth2 can be used as an alternative to a public SSH key or basic authentication (user/password) to obtain the required read or write access permissions. It relies on a Git credential helpers such as:

They are both pre-configured server side but need to be installed and configured client side. The following example uses git-credential-oauth on a Debian GNU/Linux machine to authenticate on https://code.forgejo.org:

download the binary tarball
extract the binary in /usr/local/bin/git-credential-oauth
verify it is found with git credential-oauth

add the following to ~/gitconfig (note that a4792ccc-144e-407e-86c9-5e7d8d9c3269 is a hardcoded value that is identical for all Forgejo instances)

[credential]
  helper = cache --timeout 7200
  helper = oauth
[credential "https://code.forgejo.org"]
  oauthClientId = a4792ccc-144e-407e-86c9-5e7d8d9c3269
  oauthAuthURL = /login/oauth/authorize
  oauthTokenURL = /login/oauth/access_token

git clone https://code.forgejo.org/earl-warren/test
git push will open new page on the default browser, looking like this:
subsequent git push will re-use the token obtained from OAuth2 as long as it remains in the git credential-cache (i.e. 2h / 7200s)

NOTE: Scopes are not implemented for OAuth2 tokens and they can be used to execute any actions on behalf the user, not just git related actions. Scoped applications tokens or SSH keys limited to interactions with the repository should be prefered in environments where security is a concern.

It is possible for any user to manually register a new OAuth2 application in the /user/settings/applications page for the purpose of using a Git credential helpers different from the pre-registered ones. In that case the ~/gitconfig setting (oauthClientId etc.) needs to be adapted accrodingly

Examples

Confidential client

Note: This example does not use PKCE.

Redirect the user to the authorization endpoint in order to get their consent for accessing the resources:
```
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 sent back to your application after the user authorizes. The state parameter is optional but should be used to prevent CSRF attacks.

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:
```
https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
```

Using the provided code from the redirect, you can request a new application and refresh token. The access token endpoint accepts POST requests with application/json and application/x-www-form-urlencoded body, for example:

POST https://[YOUR-FORGEJO-URL]/login/oauth/access_token

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "RETURNED_CODE",
  "grant_type": "authorization_code",
  "redirect_uri": "REDIRECT_URI"
}

Response:

{
  "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.

Use the access_token to make API requests to access the user's resources.

Public client (PKCE)

PKCE (Proof Key for Code Exchange) is an extension to the OAuth flow which allows for a secure credential exchange without the requirement to provide a client secret.

Note: Please ensure you have registered your OAuth application as a public client.

To achieve this, you have to provide a code_verifier for every authorization request. A code_verifier has to be a random string with a minimum length of 43 characters and a maximum length of 128 characters. It can contain alphanumeric characters as well as the characters -, ., _ and ~.

Using this code_verifier string, a new one called code_challenge is created by using one of two methods:

If you have the required functionality on your client, set code_challenge to be a URL-safe base64-encoded string of the SHA256 hash of code_verifier. In that case, your code_challenge_method becomes S256.
If you are unable to do so, you can provide your code_verifier as a plain string to code_challenge. Then you have to set your code_challenge_method as plain.

After you have generated this values, you can continue with your request.

Redirect the user to the authorization endpoint in order to get their consent for accessing the resources:
```
https://[YOUR-FORGEJO-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&code_challenge_method=CODE_CHALLENGE_METHOD&code_challenge=CODE_CHALLENGE&state=STATE
```
The CLIENT_ID can be obtained by registering an application in the settings. The STATE is a random string that will be sent back to your application after the user authorizes. The state parameter is optional, but should be used to prevent CSRF attacks.

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:
```
https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE
```

POST https://[YOUR-FORGEJO-URL]/login/oauth/access_token

{
  "client_id": "YOUR_CLIENT_ID",
  "code": "RETURNED_CODE",
  "grant_type": "authorization_code",
  "redirect_uri": "REDIRECT_URI",
  "code_verifier": "CODE_VERIFIER"
}