# Авторизация приложений OAuth
Вы можете разрешить другим пользователям авторизовать данные OAuth app.
> \[!NOTE]
> Рассмотрите возможность создания GitHub App вместо OAuth app.
>
> И то, OAuth apps и другое, GitHub Apps и использовать OAuth 2.0.
>
> GitHub Apps может действовать от имени пользователя, аналогичного OAuth appили как и сами, что полезно для автоматизации, которые не требуют ввода пользователем. Кроме того, GitHub Apps используйте подробные разрешения, предоставьте пользователю больше контроля над тем, к каким репозиториям приложение может получить доступ, и использовать короткие маркеры. Дополнительные сведения см. в разделе \[AUTOTITLE и [Различия между приложениями GitHub и приложениями OAuth](/ru/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)]\(/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps).
GitHubРеализация OAuth поддерживает [стандартный тип предоставления кода авторизации](https://tools.ietf.org/html/rfc6749#section-4.1) и [разрешение авторизации устройств](https://tools.ietf.org/html/rfc8628) OAuth 2.0 для приложений, у которых нет доступа к веб-браузеру.
Если вы хотите пропустить стандартную авторизацию приложения, например при его тестировании, можно воспользоваться [процессом не для веб-приложения](#non-web-application-flow).
Чтобы авторизовать приложение OAuth app, рассмотрите, какой поток авторизации лучше всего подходит вашему приложению.
* [поток веб-приложения](#web-application-flow): используется для авторизации пользователей для стандартного OAuth apps запуска в браузере. ([Тип неявного предоставления разрешений](https://tools.ietf.org/html/rfc6749#section-4.2) не поддерживается.)
* [Процесс для устройства](#device-flow): используется для автономных приложений, таких как средства CLI.
## Процесс для веб-приложения
> \[!NOTE]
> Если вы создаёте приложение на GitHub, вы всё ещё можете использовать поток веб-приложений OAuth, но у этой настройки есть важные отличия. Дополнительные сведения см. в разделе [Аутентификация с помощью приложения GitHub от имени пользователя](/ru/enterprise-server@3.22/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user) .
Процесс для веб-приложения, позволяющий авторизовать пользователей для использования приложения, состоит из следующих шагов:
1. Пользователи перенаправляются для запроса своей идентификации GitHub
2. Пользователи перенаправляются обратно на ваш сайт через GitHub
3. Приложение обращается к API с маркером доступа пользователя.
### 1. Запросить идентификацию пользователя на GitHub
```
GET http(s)://HOSTNAME/login/oauth/authorize
```
Эта конечная точка принимает следующие входные параметры.
| Параметр запроса | Тип | Обязательное? | Description |
| ---------------- | -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | `string` | Обязательное поле | Идентификатор клиента, полученный от GitHub при . |
| `redirect_uri` | `string` | Настоятельно рекомендуется | URL-адрес в приложении, на который пользователи будут направляться после авторизации. См. дополнительные сведения ниже о [URL-адресах перенаправления](#redirect-urls). |
| `login` | `string` | Необязательно | Предлагает определенную учетную запись для входа и авторизации приложения. |
| `scope` | `string` | Зависимый от контекста | Разделенный пробелами список [областей](/ru/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). Если значение не указано, по умолчанию `scope` представляет собой пустой список пользователей, которые не авторизовали ни одну область для приложения. Пользователям, авторизовавшим области для приложения, не будет отображаться страница авторизации OAuth со списком областей. Вместо этого данный шаг процесса будет автоматически завершен с набором областей, которые пользователь авторизовал для приложения. Например, если пользователь уже дважды выполнил веб-процесс и авторизовал один токен с областью `user`, а другой — с областью `repo`, третий веб-процесс без указания `scope` получит токен с областью `user` и `repo`. |
| `state` | `string` | Настоятельно рекомендуется | Случайная строка, которую сложно угадать. Используется для защиты от атак в форме подделки межсайтовых запросов. |
| | | | |
| `allow_signup` | `string` | Необязательно | Будет ли неаутентифицированным пользователям возможность зарегистрироваться на GitHub во время процесса OAuth. Значение по умолчанию — `true`. Используйте значение `false`, когда политика запрещает регистрацию. |
| `prompt` | `string` | Необязательно | Заставляет средство выбора учетной записи отображаться, если задано `select_account`значение . Средство выбора учетных записей также появится, если у приложения есть URI перенаправления, отличный от HTTP, или если у пользователя есть несколько учетных записей, вошедшего в систему. |
Параметры PKCE (ключ проверки правописания для кода Exchange) `code_challenge` и `code_challenge_method` в настоящее время не поддерживаются.
В настоящее время запросы на предварительный полет CORS (OPTIONS) не поддерживаются.
### 2. Пользователи перенаправляются обратно на ваш сайт через GitHub
Если пользователь принимает запрос, GitHub перенаправляется обратно на сайт с временным `code` параметром кода, а также состоянием, указанным на предыдущем шаге в параметре `state` . Срок действия временного кода истекает через 10 минут. Если состояния не совпадают, значит запрос создала третья сторона и следует прервать процесс.
Код в параметре `code` обменивается на маркер доступа:
```
POST http(s)://HOSTNAME/login/oauth/access_token
```
Эта конечная точка принимает следующие входные параметры.
| Наименование параметра | Тип | Обязательное? | Description |
| ---------------------- | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client_id` | `string` | Обязательное поле | Идентификатор клиента, полученный для GitHub вашего пользователя OAuth app. |
| `client_secret` | `string` | Обязательное поле | Секрет клиента, полученный от GitHub вашего клиента OAuth app. |
| `code` | `string` | Обязательное поле | Код, полученный в качестве ответа на шаге 1. |
| `redirect_uri` | `string` | Настоятельно рекомендуется | URL-адрес в приложении, на который пользователи будут направляться после авторизации. Мы можем использовать это для сопоставления с универсальным кодом ресурса (URI), первоначально предоставленного при `code` выпуске, чтобы предотвратить атаки против вашей службы. |
| | | | |
По умолчанию ответ имеет следующую форму:
```shell
access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer
```
Вы также можете получить ответ в разных форматах, указав формат в заголовке `Accept`. Например, `Accept: application/json` или `Accept: application/xml`:
```json
Accept: application/json
{
"access_token":"gho_16C7e42F292c6912E7710c838347Ae178B4a",
"scope":"repo,gist",
"token_type":"bearer"
}
```
```xml
Accept: application/xml
bearer
repo,gist
gho_16C7e42F292c6912E7710c838347Ae178B4a
```
### 3. Использование маркера доступа для доступа к API
Маркер доступа позволяет выполнять запросы к API от имени пользователя.
```
Authorization: Bearer OAUTH-TOKEN
GET http(s)://HOSTNAME/api/v3/user
```
Например, в curl можно задать заголовок авторизации следующим образом:
```shell
curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user
```
Каждый раз, когда вы получаете маркер доступа, следует использовать маркер для повторного изменения удостоверения пользователя. Пользователь может изменить учетную запись, в которую они вошли при отправке, чтобы авторизовать приложение, и вы рискуете смешивать данные пользователей, если вы не проверяете удостоверение пользователя после каждого входа.
## Процесс для устройства
Поток устройств позволяет авторизовать пользователей для приложения без головы, например средства CLI или [диспетчера учетных данных](https://github.com/git-ecosystem/git-credential-manager) Git.
Прежде чем использовать процесс для устройства с целью авторизации и идентификации пользователей, необходимо сначала включить его в параметрах приложения. Дополнительные сведения о включении потока устройств в приложении см. в разделе [Изменение регистрации приложения GitHub](/ru/enterprise-server@3.22/apps/maintaining-github-apps/modifying-a-github-app-registration) для GitHub Apps и [Изменение приложения OAuth](/ru/enterprise-server@3.22/apps/oauth-apps/maintaining-oauth-apps/modifying-an-oauth-app).OAuth apps
### Общая схема процесса для устройства
1. Приложение запрашивает коды проверки устройства и пользователя и получает URL-адрес авторизации, по которому пользователь должен будет ввести код проверки пользователя.
2. Приложение предложит пользователю ввести код проверки пользователя. `http(s)://HOSTNAME/login/device`
3. Приложение опрашивает состояние проверки подлинности пользователя. После того как пользователь авторизует устройство, приложение сможет выполнять вызовы API с новым маркером доступа.
### Шаг 1: Приложение запрашивает коды подтверждения устройства и пользователей у GitHub
```
POST http(s)://HOSTNAME/login/device/code
```
Приложение должно запросить код проверки пользователя и URL-адрес проверки, который приложение будет использовать для запроса проверки подлинности пользователя на следующем шаге. Запрос также возвращает код проверки устройства, который приложение должно использовать для получения маркера доступа и проверки состояния проверки подлинности пользователя.
Конечная точка принимает следующие входные параметры.
| Наименование параметра | Тип | Description |
| ------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | `string` | |
| **Обязательно**. Идентификатор клиента, полученный от GitHub вашего приложения. | | |
| `scope` | `string` | Список областей, к которым приложение запрашивает доступ. Дополнительные сведения см. в разделе [Области для приложений OAuth](/ru/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps). |
По умолчанию ответ имеет следующую форму:
```shell
device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%2FHOSTNAME%2Flogin%2Fdevice
```
| Наименование параметра | Тип | Description |
| ---------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `device_code` | `string` | Код проверки устройства состоит из 40 символов и служит для проверки устройства. |
| `user_code` | `string` | Код проверки пользователя отображается на устройстве, чтобы пользователь мог ввести его в браузере. Он состоит из восьми символов с дефисом в середине. |
| `verification_uri` | `string` | URL-адрес проверки, в котором пользователям необходимо ввести `user_code`: `http(s)://HOSTNAME/login/device`. |
| `expires_in` | `integer` | Количество секунд до окончания срока действия `device_code` и `user_code`. Значение по умолчанию равно 900 секундам или 15 минутам. |
| `interval` | `integer` | Минимальное количество секунд, которое должно пройти, прежде чем можно будет выполнить новый запрос маркера доступа (`POST http(s)://HOSTNAME/login/oauth/access_token`) для завершения авторизации устройства. Например, если интервал равен пяти, вы не сможете выполнить новый запрос, пока не пройдут пять секунд. Если вы выполните более одного запроса в течение пяти секунд, то достигнете предела частоты запросов и получите ошибку `slow_down`. |
Вы также можете получить ответ в разных форматах, указав формат в заголовке `Accept`. Например, `Accept: application/json` или `Accept: application/xml`:
```json
Accept: application/json
{
"device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
"user_code": "WDJB-MJHT",
"verification_uri": "http(s)://HOSTNAME/login/device",
"expires_in": 900,
"interval": 5
}
```
```xml
Accept: application/xml
3584d83530557fdd1f46af8289938c8ef79f9dc5
WDJB-MJHT
http(s)://HOSTNAME/login/device
900
5
```
### Шаг 2. Запрос на ввод кода проверки пользователя в браузере
Устройство отобразит код проверки пользователя и предложит пользователю ввести код. `http(s)://HOSTNAME/login/device`
### Шаг 3: Приложение опрошивает GitHub, чтобы проверить, авторизировал ли пользователь устройство.
```
POST http(s)://HOSTNAME/login/oauth/access_token
```
Приложение будет выполнять запросы на авторизацию устройства `POST http(s)://HOSTNAME/login/oauth/access_token`, пока не истечет срок действия кода проверки устройства или пользователя либо пока пользователь не авторизует приложение успешно с помощью допустимого кода проверки пользователя. Чтобы избежать ошибок ограничения частоты запросов, приложение должно использовать минимальный интервал (`interval`) опроса, полученный на шаге 1. Дополнительные сведения см. в разделе ["Ограничения скорости" для потока](#rate-limits-for-the-device-flow) устройств.
Пользователь должен ввести действительный код в течение 15 минут (900 секунд). По истечении 15 минут вам потребуется запросить новый код авторизации устройства с помощью `POST http(s)://HOSTNAME/login/device/code`.
После авторизации пользователем приложение получит маркер доступа, с помощью которого можно выполнять запросы к API от имени пользователя.
Конечная точка принимает следующие входные параметры.
| Наименование параметра | Тип | Description |
| ---------------------------------------------------------------------------------------------------------- | -------- | ----------- |
| `client_id` | `string` | |
| **Обязательно**. Идентификатор клиента, полученный для GitHub вашего пользователя OAuth app. | | |
| `device_code` | `string` | |
| **Обязательно**. Полученные `device_code` от `POST http(s)://HOSTNAME/login/device/code` запроса. | | |
| `grant_type` | `string` | |
| **Обязательно**. Тип предоставления разрешения должен быть `urn:ietf:params:oauth:grant-type:device_code`. | | |
По умолчанию ответ имеет следующую форму:
```shell
access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&token_type=bearer&scope=repo%2Cgist
```
Вы также можете получить ответ в разных форматах, указав формат в заголовке `Accept`. Например, `Accept: application/json` или `Accept: application/xml`:
```json
Accept: application/json
{
"access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
"token_type": "bearer",
"scope": "repo,gist"
}
```
```xml
Accept: application/xml
gho_16C7e42F292c6912E7710c838347Ae178B4a
bearer
gist,repo
```
### Ограничения частоты вызовов для процесса для устройства
Пользователь может отправлять код проверки в браузере не чаще чем 50 раз в час для каждого приложения.
При выполнении еще одного запроса маркера доступа (`POST http(s)://HOSTNAME/login/oauth/access_token`) до истечения минимального интервала времени между запросами (или `interval`) будет достигнут предел частоты запросов и получен ответ с ошибкой `slow_down`. Ответ об ошибке `slow_down` добавляет пять секунд к последнему интервалу `interval`. Дополнительные сведения см. в кодах [ошибок для потока](#error-codes-for-the-device-flow) устройства.
### Коды ошибок процесса для устройства
| Код ошибки | Description |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `authorization_pending` | Эта ошибка возникает, если запрос авторизации ожидает завершения и пользователь еще не ввел код проверки пользователя. Приложение должно продолжать выполнять запрос `POST http(s)://HOSTNAME/login/oauth/access_token` без превышения интервала `interval`, то есть перед следующим запросом должно пройти минимальное количество секунд. |
| `slow_down` | При получении ошибки `slow_down` к минимальному интервалу времени `interval` между запросами `POST http(s)://HOSTNAME/login/oauth/access_token` добавляются пять дополнительных секунд. Например, если начальный требуемый интервал между запросами составлял пять секунд и вы получили ответ с ошибкой `slow_down`, необходимо подождать не менее 10 секунд, прежде чем выполнять новый запрос маркера доступа OAuth. В ответе с ошибкой указывается новый интервал `interval`, который необходимо выждать. |
| `expired_token` | Если истек срок действия кода устройства, возникнет ошибка `token_expired`. Необходимо запросить новый код устройства. |
| `unsupported_grant_type` | Тип предоставления разрешения должен быть `urn:ietf:params:oauth:grant-type:device_code` и включен в качестве входного параметра при запросе маркера OAuth `POST http(s)://HOSTNAME/login/oauth/access_token`. |
| `incorrect_client_credentials` | Для процесса для устройства необходимо передать идентификатор клиента приложения, который можно найти на странице параметров приложения. |
| `client_secret` не требуется для процесса для устройства. | |
| `incorrect_device_code` | Указанный код проверки устройства недействителен. |
| `access_denied` | Когда пользователь нажимает кнопку "Отменить" во время процесса авторизации, вы получите `access_denied` ошибку, и пользователь не сможет снова использовать код проверки. |
| `device_flow_disabled` | Процесс для устройства не включен в параметрах приложения. Дополнительные сведения см. в разделе ["Поток](#device-flow) устройств". |
Дополнительные сведения см. в [статье OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/rfc8628#section-3.5).
## Процесс не для веб-приложения
Проверка подлинности не для веб-приложения доступна в некоторых ситуациях, таких как тестирование. Если вам нужно, можно использовать [обычную](/ru/enterprise-server@3.22/rest/authentication/authenticating-to-the-rest-api#using-basic-authentication)personal access token[personal access tokenпроверку подлинности для создания страницы параметров](/ru/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). Этот метод позволяет пользователю отозвать доступ в любое время.
## URL-адреса перенаправления
Параметр `redirect_uri` является необязательным. В противном случае GitHub перенаправит пользователей на URL-адрес обратного вызова, настроенный вOAuth app
параметры. Если это указано, узел URL-адреса перенаправления (за исключением вложенных доменов) и порт должны точно соответствовать URL-адресу обратного вызова. Путь URL-адреса перенаправления должен вести в подкаталог URL-адреса обратного вызова.
```
CALLBACK: http://example.com/path
GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
GOOD: http://oauth.example.com/path
GOOD: http://oauth.example.com/path/subdir/other
BAD: http://example.com/bar
BAD: http://example.com/
BAD: http://example.com:8080/path
BAD: http://oauth.example.com:8080/path
BAD: http://example.org
```
### URL-адреса перенаправления обратного цикла
Необязательный `redirect_uri` параметр также можно использовать для URL-адресов обратного цикла, что полезно для собственных приложений, работающих на настольном компьютере. Если приложение задает URL-адрес обратного цикла и порт, после авторизации пользователей приложения будет перенаправлено на указанный URL-адрес и порт. Не `redirect_uri` нужно соответствовать порту, указанному в URL-адресе обратного вызова для приложения.
Для URL-адреса обратного `http://127.0.0.1/path` вызова это можно использовать `redirect_uri` , если приложение прослушивает порт `1234`:
```http
http://127.0.0.1:1234/path
```
Обратите внимание, что OAuth RFC [рекомендует не использовать `localhost`](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3), а вместо этого использовать литерал `127.0.0.1` обратного цикла или IPv6 `::1`.
## Создание нескольких маркеров для OAuth apps
Вы можете создать несколько токенов для определенных сочетаний пользователя, приложения и области, которые будут предназначены для конкретных вариантов использования.
Это полезно, если поддерживается OAuth app один рабочий процесс, использующий GitHub для входа, и требуется только базовая информация о пользователе. Другой рабочий процесс может требовать доступа к частным репозиториям пользователя. Использование нескольких маркеров OAuth app позволяет выполнять веб-поток для каждого варианта использования, запрашивая только необходимые области. Если пользователь использует приложение только для входа, им никогда не требуется предоставлять OAuth app доступ к частным репозиториям.
Существует ограничение в десять маркеров, выдаваемых для каждого пользователя или приложения или области, и ограничение скорости в десять маркеров, созданных в час. Если приложение создает более десяти маркеров для одного и того же пользователя и той же области, GitHub отменяет один из существующих маркеров с одинаковым сочетанием пользователя или приложения или области, выбранного в этом порядке:
1. Самый старый маркер, который никогда не использовался.
2. Если каждый маркер использовался, маркер, который был наименее недавно использован.
При нажатии лимита почасовой скорости не отозван старый маркер. Вместо этого он активирует запрос повторной авторизации в браузере, запрашивая у пользователя двойной проверки разрешений, которые они предоставляют приложению. Этот запрос предназначен для того, чтобы дать перерыв любому потенциальному бесконечному циклу приложения зависает, так как не существует никаких причин для приложения запрашивать десять токенов от пользователя в течение часа.
> \[!WARNING]
> Отмена всех разрешений от OAuth app удаляет все ключи SSH, созданные от имени пользователя, включая [ключ развертывания](/ru/enterprise-server@3.22/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys).
## Перенаправление пользователей для проверки доступа
Вы можете ссылаться на сведения о авторизации, OAuth app чтобы пользователи могли просматривать и отзывать свои разрешения приложения.
Чтобы создать эту ссылку, вам потребуется, OAuth app`client_id` что вы получили от GitHub при регистрации приложения.
```http
http(s)://HOSTNAME/settings/connections/applications/:client_id
```
> \[!TIP]
> Дополнительные сведения о ресурсах, к которым OAuth app можно получить доступ для пользователя, см. в разделе [Обнаружение ресурсов для пользователя](/ru/enterprise-server@3.22/rest/guides/discovering-resources-for-a-user).
## Устранение неполадок
* [Устранение ошибок запросов на авторизацию](/ru/enterprise-server@3.22/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-authorization-request-errors)
* [Устранение ошибок запроса маркера доступа к приложению OAuth](/ru/enterprise-server@3.22/apps/oauth-apps/maintaining-oauth-apps/troubleshooting-oauth-app-access-token-request-errors)
* [Ошибки потока устройства](#error-codes-for-the-device-flow)
* [Истечение срока действия и отзыв маркера](/ru/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)
## Дополнительные материалы
* [Об аутентификации на GitHub](/ru/enterprise-server@3.22/authentication/keeping-your-account-and-data-secure/about-authentication-to-github)