code.gitea.io/gitea@v1.22.3/docs/content/development/oauth2-provider.en-us.md (about) 1 --- 2 date: "2023-06-01T08:40:00+08:00" 3 title: "OAuth2 provider" 4 slug: "oauth2-provider" 5 sidebar_position: 41 6 toc: false 7 draft: false 8 aliases: 9 - /en-us/oauth2-provider 10 menu: 11 sidebar: 12 parent: "development" 13 name: "OAuth2 Provider" 14 sidebar_position: 41 15 identifier: "oauth2-provider" 16 --- 17 18 # OAuth2 provider 19 20 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. 21 22 ## Endpoints 23 24 | Endpoint | URL | 25 | ------------------------ | ----------------------------------- | 26 | OpenID Connect Discovery | `/.well-known/openid-configuration` | 27 | Authorization Endpoint | `/login/oauth/authorize` | 28 | Access Token Endpoint | `/login/oauth/access_token` | 29 | OpenID Connect UserInfo | `/login/oauth/userinfo` | 30 | JSON Web Key Set | `/login/oauth/keys` | 31 32 ## Supported OAuth2 Grants 33 34 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: 35 36 - [Proof Key for Code Exchange (PKCE)](https://tools.ietf.org/html/rfc7636) 37 - [OpenID Connect (OIDC)](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) 38 39 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/. 40 41 ## Scopes 42 43 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: 44 45 - `read`: `GET` routes 46 - `write`: `POST`, `PUT`, `PATCH`, and `DELETE` routes (in addition to `GET`) 47 48 Gitea token scopes are as follows: 49 50 | Name | Description | 51 | ---- |------------------------------------------------------------------------------------------------------------------------------------------------------| 52 | **(no scope)** | Not supported. A scope is required even for public repositories. | 53 | **activitypub** | `activitypub` API routes: ActivityPub related operations. | 54 | **read:activitypub** | Grants read access for ActivityPub operations. | 55 | **write:activitypub** | Grants read/write/delete access for ActivityPub operations. | 56 | **admin** | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts). | 57 | **read:admin** | Grants read access for admin operations, such as getting cron jobs or registered user emails. | 58 | **write:admin** | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts. | 59 | **issue** | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations. | 60 | **read:issue** | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones. | 61 | **write:issue** | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones. | 62 | **misc** | Reserved for future usage. | 63 | **read:misc** | Reserved for future usage. | 64 | **write:misc** | Reserved for future usage. | 65 | **notification** | `notification/*` API routes: user notification operations. | 66 | **read:notification** | Grants read access to user notifications, such as which notifications users are subscribed to and read new notifications. | 67 | **write:notification** | Grants read/write/delete access to user notifications, such as marking notifications as read. | 68 | **organization** | `orgs/*` and `teams/*` API routes: Organization and team management operations. | 69 | **read:organization** | Grants read access to org and team status, such as listing all orgs a user has visibility to, teams, and team members. | 70 | **write:organization** | Grants read/write/delete access to org and team status, such as creating and updating teams and updating org settings. | 71 | **package** | `/packages/*` API routes: Packages operations | 72 | **read:package** | Grants read access to package operations, such as reading and downloading available packages. | 73 | **write:package** | Grants read/write/delete access to package operations. Currently the same as `read:package`. | 74 | **repository** | `/repos/*` API routes except `/repos/issues/*`: Repository file, pull-request, and release operations. | 75 | **read:repository** | Grants read access to repository operations, such as getting repository files, releases, collaborators. | 76 | **write:repository** | Grants read/write/delete access to repository operations, such as getting updating repository files, creating pull requests, updating collaborators. | 77 | **user** | `/user/*` and `/users/*` API routes: User-related operations. | 78 | **read:user** | Grants read access to user operations, such as getting user repo subscriptions and user settings. | 79 | **write:user** | Grants read/write/delete access to user operations, such as updating user repo subscriptions, followed users, and user settings. | 80 81 ## Pre-configured Applications 82 83 Gitea creates OAuth applications for the following services by default on startup, as we assume that these are universally useful. 84 85 |Application|Description|Client ID| 86 |-----------|-----------|---------| 87 |[git-credential-oauth](https://github.com/hickford/git-credential-oauth)|Git credential helper|`a4792ccc-144e-407e-86c9-5e7d8d9c3269`| 88 |[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)|Git credential helper|`e90ee53c-94e2-48ac-9358-a874fb9e0662`| 89 |[tea](https://gitea.com/gitea/tea)|tea|`d57cb8c4-630c-4168-8324-ec79935e18d4`| 90 91 To prevent unexpected behavior, they are being displayed as locked in the UI and their creation can instead be controlled by the `DEFAULT_APPLICATIONS` parameter in `app.ini`. 92 93 ## Client types 94 95 Gitea supports both confidential and public client types, [as defined by RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1). 96 97 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). 98 99 ## Examples 100 101 ### Confidential client 102 103 **Note:** This example does not use PKCE. 104 105 1. Redirect the user to the authorization endpoint in order to get their consent for accessing the resources: 106 107 ```curl 108 https://[YOUR-GITEA-URL]/login/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE 109 ``` 110 111 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. 112 113  114 115 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: 116 117 ```curl 118 https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE 119 ``` 120 121 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: 122 123 ```curl 124 POST https://[YOUR-GITEA-URL]/login/oauth/access_token 125 ``` 126 127 ```json 128 { 129 "client_id": "YOUR_CLIENT_ID", 130 "client_secret": "YOUR_CLIENT_SECRET", 131 "code": "RETURNED_CODE", 132 "grant_type": "authorization_code", 133 "redirect_uri": "REDIRECT_URI" 134 } 135 ``` 136 137 Response: 138 139 ```json 140 { 141 "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug", 142 "token_type": "bearer", 143 "expires_in": 3600, 144 "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw" 145 } 146 ``` 147 148 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. 149 150 The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request. 151 152 3. Use the `access_token` to make [API requests](development/api-usage.md#oauth2-provider) to access the user's resources. 153 154 ### Public client (PKCE) 155 156 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. 157 158 **Note**: Please ensure you have registered your OAuth application as a public client. 159 160 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 `~`. 161 162 Using this `code_verifier` string, a new one called `code_challenge` is created by using one of two methods: 163 164 - 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`. 165 - 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`. 166 167 After you have generated this values, you can continue with your request. 168 169 1. Redirect the user to the authorization endpoint in order to get their consent for accessing the resources: 170 171 ```curl 172 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 173 ``` 174 175 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. 176 177  178 179 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: 180 181 ```curl 182 https://[REDIRECT_URI]?code=RETURNED_CODE&state=STATE 183 ``` 184 185 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: 186 187 ```curl 188 POST https://[YOUR-GITEA-URL]/login/oauth/access_token 189 ``` 190 191 ```json 192 { 193 "client_id": "YOUR_CLIENT_ID", 194 "code": "RETURNED_CODE", 195 "grant_type": "authorization_code", 196 "redirect_uri": "REDIRECT_URI", 197 "code_verifier": "CODE_VERIFIER", 198 } 199 ``` 200 201 Response: 202 203 ```json 204 { 205 "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjowLCJleHAiOjE1NTUxNzk5MTIsImlhdCI6MTU1NTE3NjMxMn0.0-iFsAwBtxuckA0sNZ6QpBQmywVPz129u75vOM7wPJecw5wqGyBkmstfJHAjEOqrAf_V5Z-1QYeCh_Cz4RiKug", 206 "token_type": "bearer", 207 "expires_in": 3600, 208 "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJnbnQiOjIsInR0IjoxLCJjbnQiOjEsImV4cCI6MTU1NzgwNDMxMiwiaWF0IjoxNTU1MTc2MzEyfQ.S_HZQBy4q9r5SEzNGNIoFClT43HPNDbUdHH-GYNYYdkRfft6XptJBkUQscZsGxOW975Yk6RbgtGvq1nkEcklOw" 209 } 210 ``` 211 212 The `REDIRECT_URI` in the `access_token` request must match the `REDIRECT_URI` in the `authorize` request. 213 214 3. Use the `access_token` to make [API requests](development/api-usage.md#oauth2-provider) to access the user's resources.