mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-04 17:19:52 +00:00
Add version v28 (#564)
<!-- cloudflare-preview --> Preview: https://pr-564.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/564 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]>
This commit is contained in:
Lunny Xiao authored and 
bircni committed
1 parent
deb2f068d4
commit
ba60edbbda
338 files changed
+114457
-47
No files matched your search
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Development",
|
||||
"position": 40,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/development",
|
||||
"title": "Development"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,163 @@
|
||||
---
|
||||
date: "2018-06-24:00:00+02:00"
|
||||
slug: "api-usage"
|
||||
sidebar_position: 40
|
||||
aliases:
|
||||
- /en-us/api-usage
|
||||
---
|
||||
|
||||
# API Usage
|
||||
|
||||
## Enabling/configuring API access
|
||||
|
||||
By default, `ENABLE_SWAGGER` is true, and `MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat Sheet](../administration/config-cheat-sheet.md) for more information.
|
||||
|
||||
## Authentication
|
||||
|
||||
Gitea supports these methods of API authentication:
|
||||
|
||||
- HTTP basic authentication
|
||||
- `token=...` parameter in URL query string
|
||||
- `access_token=...` parameter in URL query string
|
||||
- `Authorization: token ...` header in HTTP headers
|
||||
- HTTP signatures using an SSH public key or SSH certificate
|
||||
|
||||
All of these methods accept the same API key token type. You can
|
||||
better understand this by looking at the code -- as of this writing,
|
||||
Gitea parses queries and headers to find the token in
|
||||
[modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
|
||||
|
||||
Gitea can also authenticate API requests using an SSH key or SSH certificate via
|
||||
HTTP signatures. The SSH public key (or certificate) must be registered to the
|
||||
user account in Gitea, and the client signs requests with the corresponding
|
||||
private key. The client signs requests using the SSH private key following the
|
||||
[draft-cavage-http-signatures](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures)
|
||||
specification (not RFC 9421). The signature is sent in the `Signature` header,
|
||||
and SSH certificates additionally include an `x-ssh-certificate` header. The
|
||||
official [go-sdk](https://gitea.com/gitea/go-sdk) implements this flow if you
|
||||
need a reference implementation.
|
||||
|
||||
## Generating and listing API tokens
|
||||
|
||||
API tokens can be created either in the user interface or via the API. Tokens have by default limited permissions and it is important to create tokens with the correct permissions for your task.
|
||||
### User Interface
|
||||
Tokens can be created via the `Manage Access Tokens` dialog, accessed via `User Settings` / `Applications` or via the link `gitea-domain.example/user/settings/applications`. The interface allows you to create tokens and manage their permissions via the `Select permissions` sub-menu.
|
||||
|
||||
Once created, the token is displayed in a toast message above the `Manage Access Tokens` dialog. Please note, that you can view this toast only once and it is not possible to redisplay the token for security reasons.
|
||||
|
||||
### Token API
|
||||
|
||||
A new token can be generated with a `POST` request to
|
||||
`/users/:name/tokens`.
|
||||
|
||||
Note that `/users/:name/tokens` is a special endpoint and requires you
|
||||
to authenticate using `BasicAuth` and a password, as follows:
|
||||
|
||||
```sh
|
||||
$ curl -H "Content-Type: application/json" \
|
||||
-d '{"name":"test_token","scopes":["read:activitypub","read:issue", "write:misc", "read:notification", "read:organization", "read:package", "read:repository", "read:user"]}' \
|
||||
-u 'username:password' "https://gitea.your.host/api/v1/users/{username}/tokens"
|
||||
{"id":1,"name":"test_token","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
|
||||
```
|
||||
|
||||
The ``sha1`` (the token) is only returned once and is not stored in
|
||||
plain-text. It will not be displayed when listing tokens with a `GET`
|
||||
request; e.g.
|
||||
|
||||
```sh
|
||||
$ curl --url https://yourusername:[email protected]/api/v1/users/<username>/tokens
|
||||
[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
|
||||
```
|
||||
|
||||
By default, this creates a token with very limited permissions. To complete your tasks, your token may require extra permissions. These permissions are created via the json variable `scopes`, which takes an array of permissions as strings. Eg.: `"scopes":["all"]`. Possible permissions, as reflected in the user interface are:
|
||||
|
||||
- `activitypub`
|
||||
- `admin`
|
||||
- `issue`
|
||||
- `misc`
|
||||
- `notification`
|
||||
- `organization`
|
||||
- `package`
|
||||
- `repository`
|
||||
- `user`
|
||||
|
||||
Each permission may be set to `read` or `write`. `write` implies both Read & Write. To set permissions you write the permissions string as `<read or write>:<permission name>`, eg.: `write:package` or `read:notification`. A properly formatted API call may look like:
|
||||
|
||||
```sh
|
||||
$ curl -H "Content-Type: application/json" -d '{"name":"test", "scopes":["write:package", "read:notification"]}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
|
||||
```
|
||||
Special permissions `all` may be specified as `"scopes":["all"]`, which sets all permissions to both Read & Write.
|
||||
|
||||
To use the API with basic authentication with two factor authentication
|
||||
enabled, you'll need to send an additional header that contains the one
|
||||
time password (6 digitrotating token).
|
||||
An example of the header is `X-Gitea-OTP: 123456` where `123456`
|
||||
is where you'd place the code from your authenticator.
|
||||
Here is how the request would look like in curl:
|
||||
|
||||
```sh
|
||||
$ curl -H "X-Gitea-OTP: 123456" --url https://yourusername:[email protected]/api/v1/users/yourusername/tokens
|
||||
```
|
||||
|
||||
You can also create an API key token via your Gitea installation's web
|
||||
interface: `Settings | Applications | Generate New Token`.
|
||||
|
||||
## OAuth2 Provider
|
||||
|
||||
Access tokens obtained from Gitea's [OAuth2 provider](development/oauth2-provider.md) are accepted by these methods:
|
||||
|
||||
- `Authorization bearer ...` header in HTTP headers
|
||||
- `token=...` parameter in URL query string
|
||||
- `access_token=...` parameter in URL query string
|
||||
|
||||
### More on the `Authorization:` header
|
||||
|
||||
For historical reasons, Gitea needs the word `token` included before
|
||||
the API key token in an authorization header, like this:
|
||||
|
||||
```sh
|
||||
Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
|
||||
```
|
||||
|
||||
In a `curl` command, for instance, this would look like:
|
||||
|
||||
```sh
|
||||
curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
|
||||
-H "accept: application/json" \
|
||||
-H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
|
||||
-H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
|
||||
```
|
||||
|
||||
As mentioned above, the token used is the same one you would use in
|
||||
the `token=` string in a GET request.
|
||||
|
||||
## Pagination
|
||||
|
||||
The API supports pagination. The `page` and `limit` parameters are used to specify the page number and the number of items per page. As well, the `Link` header is returned with the next, previous, and last page links if there are more than one pages. The `x-total-count` is also returned to indicate the total number of items.
|
||||
|
||||
```sh
|
||||
curl -v "http://localhost/api/v1/repos/search?limit=1"
|
||||
...
|
||||
< link: <http://localhost/api/v1/repos/search?limit=1&page=2>; rel="next",<http://localhost/api/v1/repos/search?limit=1&page=5252>; rel="last"
|
||||
...
|
||||
< x-total-count: 5252
|
||||
```
|
||||
|
||||
## API Guide
|
||||
|
||||
API Reference guide is auto-generated by swagger and available on:
|
||||
`https://gitea.your.host/api/swagger`
|
||||
or on the
|
||||
[Gitea instance](https://gitea.com/api/swagger)
|
||||
|
||||
The OpenAPI document is at:
|
||||
`https://gitea.your.host/swagger.v1.json`
|
||||
|
||||
## Sudo
|
||||
|
||||
The API allows admin users to sudo API requests as another user. Simply add either a `sudo=` parameter or `Sudo:` request header with the username of the user to sudo.
|
||||
|
||||
## SDKs
|
||||
|
||||
- [Official go-sdk](https://gitea.com/gitea/go-sdk)
|
||||
- [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk)
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
date: "2019-04-15T17:29:00+08:00"
|
||||
slug: "integrations"
|
||||
sidebar_position: 65
|
||||
aliases:
|
||||
- /en-us/integrations
|
||||
---
|
||||
|
||||
# Integrations
|
||||
|
||||
Gitea has a wonderful community of third-party integrations, as well as first-class support in various other
|
||||
projects.
|
||||
|
||||
We are curating a list over at [awesome-gitea](https://gitea.com/gitea/awesome-gitea) to track these!
|
||||
|
||||
If you are looking for [CI/CD](https://gitea.com/gitea/awesome-gitea#user-content-devops),
|
||||
an [SDK](https://gitea.com/gitea/awesome-gitea#user-content-sdk),
|
||||
or even some extra [themes](https://gitea.com/gitea/awesome-gitea#user-content-themes),
|
||||
you can find them listed in the [awesome-gitea](https://gitea.com/gitea/awesome-gitea) repository!
|
||||
|
||||
## Pre-Fill New File name and contents
|
||||
|
||||
If you'd like to open a new file with a given name and contents,
|
||||
you can do so with query parameters:
|
||||
|
||||
```txt
|
||||
GET /{{org}}/{{repo}}/_new/{{filepath}}
|
||||
?filename={{filename}}
|
||||
&value={{content}}
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```txt
|
||||
GET https://git.example.com/johndoe/bliss/_new/articles/
|
||||
?filename=hello-world.md
|
||||
&value=Hello%2C%20World!
|
||||
```
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
date: "2019-04-15T17:29:00+08:00"
|
||||
slug: "migrations-interfaces"
|
||||
sidebar_position: 55
|
||||
aliases:
|
||||
- /en-us/migrations-interfaces
|
||||
---
|
||||
|
||||
# Migration Interfaces
|
||||
|
||||
Complete migrations were introduced in Gitea 1.9.0. It defines two interfaces to support migrating
|
||||
repository data from other Git host platforms to Gitea or, in the future, migrating Gitea data to other Git host platforms.
|
||||
|
||||
Currently, migrations from GitHub, GitLab, and other Gitea instances are implemented.
|
||||
|
||||
First of all, Gitea defines some standard objects in packages [modules/migration](https://github.com/go-gitea/gitea/tree/main/modules/migration).
|
||||
They are `Repository`, `Milestone`, `Release`, `ReleaseAsset`, `Label`, `Issue`, `Comment`, `PullRequest`, `Reaction`, `Review`, `ReviewComment`.
|
||||
|
||||
## Downloader Interfaces
|
||||
|
||||
To migrate from a new Git host platform, there are two steps to be updated.
|
||||
|
||||
- You should implement a `Downloader` which will be used to get repository information.
|
||||
- You should implement a `DownloaderFactory` which will be used to detect if the URL matches and create the above `Downloader`.
|
||||
- You'll need to register the `DownloaderFactory` via `RegisterDownloaderFactory` on `init()`.
|
||||
|
||||
You can find these interfaces in [downloader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/downloader.go).
|
||||
|
||||
## Uploader Interface
|
||||
|
||||
Currently, only a `GiteaLocalUploader` is implemented, so we only save downloaded
|
||||
data via this `Uploader` to the local Gitea instance. Other uploaders are not supported at this time.
|
||||
|
||||
You can find these interfaces in [uploader.go](https://github.com/go-gitea/gitea/blob/main/modules/migration/uploader.go).
|
||||
@@ -0,0 +1,271 @@
|
||||
---
|
||||
date: "2023-06-01T08:40:00+08:00"
|
||||
slug: "oauth2-provider"
|
||||
sidebar_position: 41
|
||||
aliases:
|
||||
- /en-us/oauth2-provider
|
||||
---
|
||||
|
||||
# OAuth2 Provider
|
||||
|
||||
Gitea supports acting as an OAuth2 Provider, allowing third-party applications to access its resources with user consent.
|
||||
|
||||
When acting as the OAuth2 Provider, Gitea verifies every authorization request against the related OAuth2 Application. This application can be set up by an individual user, an organization admin, or a Gitea instance admin.
|
||||
|
||||
Regardless of who configured the application, the first authorization attempt opens a new page in the user's web browser, prompting them to authorize the application.
|
||||
|
||||
## Configuration
|
||||
|
||||
An OAuth2 Application in Gitea requires the following configuration made in two steps:
|
||||
|
||||
### Gitea Step 1
|
||||
- Name (`/admin/applications/`)
|
||||
- Redirect URL (`/admin/applications/`)
|
||||
|
||||
|
||||
|
||||
### Gitea Step 2
|
||||
- Client ID (`/admin/applications/oauth2/_id_`)
|
||||
- Client Secret (`/admin/applications/oauth2/_id_`)
|
||||
- Confidential client status (`/admin/applications/oauth2/_id_`)
|
||||
|
||||
|
||||
|
||||
### Third Party Step 3
|
||||
|
||||
The third-party (Relaying Parties) application's request must include:
|
||||
|
||||
- Credentials (Client ID and Client Secret)
|
||||
- Desired scope and claims (expected to be provided by Gitea)
|
||||
|
||||
An example of MinIO:
|
||||
|
||||
|
||||
|
||||
|
||||
### Gitea's User Approval Step 3
|
||||
|
||||
For example, logging in with a Gitea account on MinIO...
|
||||
|
||||
|
||||
...will display the approval popup after a successful login:
|
||||
|
||||
|
||||
By default, if the third party sets the scopes to `openid`, `email`, `profile`, and `groups`, and the user approves, the application gains full access to all of the user's public and private resources (repositories, issues, user information, etc.).
|
||||
|
||||
> **NOTE:** At present, an admin who sets up the OAuth2 Application in Gitea must rely on the scopes sent by the third party and an approval decision by the informed user if restrictive access is expected. There is no way for the admin to set restrictive access via scopes during the application setup process.
|
||||
|
||||
|
||||
## Granular Scopes
|
||||
|
||||
As of version v1.23, Gitea supports granular scopes, allowing third parties to request more limited access. These scopes, previously available only for [Personal Access Tokens](#scopes), enable users to restrict access to specific URL routes.
|
||||
|
||||
Scopes are grouped by high-level API routes and further refined as follows:
|
||||
|
||||
- `read`: `GET` routes
|
||||
- `write`: `POST`, `PUT`, `PATCH`, and `DELETE` routes (in addition to `GET`)
|
||||
|
||||
For example, a third party can request minimal access, allowing Gitea to act as a simple OpenID Connect (OIDC) Provider. If the third party adds only `public-only` to 'openid', no other or any combination of the scopes `email`, `userinfo`, or `groups`, Gitea will act as a basic Single Sign-On provider. This configuration provides only verification that the user can log in with the correct credentials, supplying only basic information such as username, email, and a list of public memberships in organizations and teams.
|
||||
|
||||
When any of the granular scopes known from Personal Access Tokens is introduced, Gitea will not allow full access (as it does by default). Instead, it will build granular access following read or write permissions to resources such as Repositories, Issues, ActivityPub, Admin functions, Organizations, Users, Packages, or miscellaneous features.
|
||||
|
||||
> **NOTE:** If third party adds any scope other than the OIDC ones: `openid`, `email`, `profile`, and `groups` or the ones found already in Personal Access Token the scope will fallback to full access as it was the case before v1.23
|
||||
|
||||
The approval page displayed to the user shows the list of scopes requested by the third party. Once approved, this decision is remembered. If the third party changes its requested scopes in future requests, the entire flow will fail, requiring re-authorization.
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Endpoint | URL |
|
||||
| ------------------------ | ----------------------------------- |
|
||||
| OpenID Connect Discovery | `/.well-known/openid-configuration` |
|
||||
| Authorization Endpoint | `/login/oauth/authorize` |
|
||||
| Access Token Endpoint | `/login/oauth/access_token` |
|
||||
| Token Introspection Endpoint | `/login/oauth/introspect` |
|
||||
| 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**](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. 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** | Reserved for future usage. |
|
||||
| **read:misc** | Reserved for future usage. |
|
||||
| **write:misc** | Reserved for future usage. |
|
||||
| **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. |
|
||||
|
||||
## Pre-configured Applications
|
||||
|
||||
Gitea creates OAuth applications for the following services by default on startup, as we assume that these are universally useful.
|
||||
|
||||
|Application|Description|Client ID|
|
||||
|-----------|-----------|---------|
|
||||
|[git-credential-oauth](https://github.com/hickford/git-credential-oauth)|Git credential helper|`a4792ccc-144e-407e-86c9-5e7d8d9c3269`|
|
||||
|[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)|Git credential helper|`e90ee53c-94e2-48ac-9358-a874fb9e0662`|
|
||||
|[tea](https://gitea.com/gitea/tea)|tea|`d57cb8c4-630c-4168-8324-ec79935e18d4`|
|
||||
|
||||
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`.
|
||||
|
||||
## Client types
|
||||
|
||||
Gitea 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).
|
||||
|
||||
## 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:
|
||||
|
||||
```curl
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 endpoint accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
|
||||
|
||||
```curl
|
||||
POST https://[YOUR-GITEA-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 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](development/api-usage.md#oauth2-provider) 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:
|
||||
|
||||
```curl
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 endpoint accepts POST requests with `application/json` and `application/x-www-form-urlencoded` body, for example:
|
||||
|
||||
```curl
|
||||
POST https://[YOUR-GITEA-URL]/login/oauth/access_token
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"client_id": "YOUR_CLIENT_ID",
|
||||
"code": "RETURNED_CODE",
|
||||
"grant_type": "authorization_code",
|
||||
"redirect_uri": "REDIRECT_URI",
|
||||
"code_verifier": "CODE_VERIFIER",
|
||||
}
|
||||
```
|
||||
|
||||
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 `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](development/api-usage.md#oauth2-provider) to access the user's resources.
|
||||
Reference in new issue
Block a user