forgejo/docs/content/doc/development/oauth2-provider.en-us.md
Jack Hay 18de83b2a3
Redesign Scoped Access Tokens (#24767)
## Changes
- Adds the following high level access scopes, each with `read` and
`write` levels:
    - `activitypub`
    - `admin` (hidden if user is not a site admin)
    - `misc`
    - `notification`
    - `organization`
    - `package`
    - `issue`
    - `repository`
    - `user`
- Adds new middleware function `tokenRequiresScopes()` in addition to
`reqToken()`
  -  `tokenRequiresScopes()` is used for each high-level api section
- _if_ a scoped token is present, checks that the required scope is
included based on the section and HTTP method
  - `reqToken()` is used for individual routes
- checks that required authentication is present (but does not check
scope levels as this will already have been handled by
`tokenRequiresScopes()`
- Adds migration to convert old scoped access tokens to the new set of
scopes
- Updates the user interface for scope selection

### User interface example
<img width="903" alt="Screen Shot 2023-05-31 at 1 56 55 PM"
src="https://github.com/go-gitea/gitea/assets/23248839/654766ec-2143-4f59-9037-3b51600e32f3">
<img width="917" alt="Screen Shot 2023-05-31 at 1 56 43 PM"
src="https://github.com/go-gitea/gitea/assets/23248839/1ad64081-012c-4a73-b393-66b30352654c">

## tokenRequiresScopes  Design Decision
- `tokenRequiresScopes()` was added to more reliably cover api routes.
For an incoming request, this function uses the given scope category
(say `AccessTokenScopeCategoryOrganization`) and the HTTP method (say
`DELETE`) and verifies that any scoped tokens in use include
`delete:organization`.
- `reqToken()` is used to enforce auth for individual routes that
require it. If a scoped token is not present for a request,
`tokenRequiresScopes()` will not return an error

## TODO
- [x] Alphabetize scope categories
- [x] Change 'public repos only' to a radio button (private vs public).
Also expand this to organizations
- [X] Disable token creation if no scopes selected. Alternatively, show
warning
- [x] `reqToken()` is missing from many `POST/DELETE` routes in the api.
`tokenRequiresScopes()` only checks that a given token has the correct
scope, `reqToken()` must be used to check that a token (or some other
auth) is present.
   -  _This should be addressed in this PR_
- [x] The migration should be reviewed very carefully in order to
minimize access changes to existing user tokens.
   - _This should be addressed in this PR_
- [x] Link to api to swagger documentation, clarify what
read/write/delete levels correspond to
- [x] Review cases where more than one scope is needed as this directly
deviates from the api definition.
   - _This should be addressed in this PR_
   - For example: 
   ```go
	m.Group("/users/{username}/orgs", func() {
		m.Get("", reqToken(), org.ListUserOrgs)
		m.Get("/{org}/permissions", reqToken(), org.GetUserOrgsPermissions)
}, tokenRequiresScopes(auth_model.AccessTokenScopeCategoryUser,
auth_model.AccessTokenScopeCategoryOrganization),
context_service.UserAssignmentAPI())
   ```

## Future improvements
- [ ] Add required scopes to swagger documentation
- [ ] Redesign `reqToken()` to be opt-out rather than opt-in
- [ ] Subdivide scopes like `repository`
- [ ] Once a token is created, if it has no scopes, we should display
text instead of an empty bullet point
- [ ] If the 'public repos only' option is selected, should read
categories be selected by default

Closes #24501
Closes #24799

Co-authored-by: Jonathan Tran <jon@allspice.io>
Co-authored-by: Kyle D <kdumontnu@gmail.com>
Co-authored-by: silverwind <me@silverwind.io>
2023-06-04 20:57:16 +02:00

13 KiB

date title slug weight toc draft aliases menu
2023-06-01T08:40:00+08:00 OAuth2 provider oauth2-provider 41 false false
/en-us/oauth2-provider
sidebar
parent name weight identifier
development OAuth2 Provider 41 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 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/.

Scopes

Gitea supports scoped access tokens, which allow users the ability to restrict tokens to operate only on selected url routes. Scopes are grouped by high-level API routes, and further refined to the following:

  • read: GET routes
  • write: POST, PUT, PATCH, and DELETE routes (in addition to GET)

Gitea token scopes are as follows:

Name Description
(no scope) Not supported. A scope is required even for public repositories.
activitypub activitypub API routes: ActivityPub related operations.
    read:activitypub Grants read access for ActivityPub operations.
    write:activitypub Grants read/write/delete access for ActivityPub operations.
admin /admin/* API routes: Site-wide administrative operations (hidden for non-admin accounts).
    read:admin Grants read access for admin operations, such as getting cron jobs or registered user emails.
    write:admin Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts.
issue issues/*, labels/*, milestones/* API routes: Issue-related operations.
    read:issue Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones.
    write:issue Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones.
misc miscellaneous and settings top-level API routes.
    read:misc Grants read access to miscellaneous operations, such as getting label and gitignore templates.
    write:misc Grants read/write/delete access to miscellaneous operations, such as markup utility operations.
notification notification/* API routes: user notification operations.
    read:notification Grants read access to user notifications, such as which notifications users are subscribed to and read new notifications.
    write:notification Grants read/write/delete access to user notifications, such as marking notifications as read.
organization orgs/* and teams/* API routes: Organization and team management operations.
    read:organization Grants read access to org and team status, such as listing all orgs a user has visibility to, teams, and team members.
    write:organization Grants read/write/delete access to org and team status, such as creating and updating teams and updating org settings.
package /packages/* API routes: Packages operations
    read:package Grants read access to package operations, such as reading and downloading available packages.
    write:package Grants read/write/delete access to package operations. Currently the same as read:package.
repository /repos/* API routes except /repos/issues/*: Repository file, pull-request, and release operations.
    read:repository Grants read access to repository operations, such as getting repository files, releases, collaborators.
    write:repository Grants read/write/delete access to repository operations, such as getting updating repository files, creating pull requests, updating collaborators.
user /user/* and /users/* API routes: User-related operations.
    read:user Grants read access to user operations, such as getting user repo subscriptions and user settings.
    write:user Grants read/write/delete access to user operations, such as updating user repo subscriptions, followed users, and user settings.

Client types

Gitea 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.

Examples

Confidential client

Note: This example does not use PKCE.

  1. Redirect the user to the authorization endpoint in order to get their consent for accessing the resources:

    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 sent back to your application after the user authorizes. The state parameter is optional, but should be used to prevent CSRF attacks.

    Authorization Page

    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
    
  2. 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-GITEA-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 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 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.

  1. Redirect the user to the authorization endpoint in order to get their consent for accessing the resources:

    https://[YOUR-GITEA-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.

    Authorization Page

    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
    
  2. 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-GITEA-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",
    }
    

    Response:

    {
      "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug",
      "token_type": "bearer",
      "expires_in": 3600,
      "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw"
    }
    

    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 to access the user's resources.