← Cloudflare Fundamentals / fundamentals / oauth

Создание OAuth-клиента

Предварительные требования

Чтобы создать клиент OAuth, у вас должна быть одна из следующих ролей для соответствующей учётной записи: Super Administrator, Administrator или OAuth Client Write.

Войдите в панель управления Cloudflare.
Выберите аккаунт.
Перейдите в Manage Account > OAuth-клиенты.
Выберите Создание клиента.
Введите необходимые данные конфигурации:
- Имя клиента
- Тип ответа
- Grant type
- Метод аутентификации по токену
- URL-адреса перенаправления
Необязательно: добавьте поля, которые не являются обязательными.
Выберите Продолжение и определите области доступа (scopes), необходимые для вашего клиента.
Необязательно: в Выберите дополнительные области действия, отключите Обязательный для каждой области доступа, которую нужно сделать необязательной. По умолчанию все области доступа обязательны.
Выберите Создание клиента.
Сохраните ваш Client ID и Секрет клиента в надежном месте.

Перейдите в OAuth-клиенты ↗

Чтобы создавать клиенты OAuth через Cloudflare API, создайте API-токен с OAuth Clients Write разрешение.

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer $API_TOKEN" \
	-d '{
		"client_name": "Cloudflare OAuth Client",
		"grant_types": ["authorization_code"],
		"redirect_uris": ["https://example.com/oauth/callback"],
		"scopes": ["workers-platform.read", "workers-platform.write"],
		"optional_scopes": ["workers-platform.read"],
		"post_logout_redirect_uris": ["https://example.com/logout"],
		"response_types": ["code"],
		"token_endpoint_auth_method": "client_secret_basic",
		"logo_uri": "https://example.com/logo.png",
		"policy_uri": "https://example.com/policy",
		"tos_uri": "https://example.com/tos",
		"client_uri": "https://example.com",
		"allowed_cors_origins": ["https://example.com"]
	}'

Выберите области действия

Названия OAuth-scope соответствуют названиям разрешений API-токенов Cloudflare. Используйте документацию Cloudflare по API, чтобы определить разрешения, необходимые вашему клиенту.

При создании или редактировании OAuth клиента выберите хотя бы одно разрешение. Все выбранные разрешения по умолчанию являются обязательными.

В Выберите дополнительные области действия, отключите Обязательный для каждой области действия, которую нужно сделать необязательной.

Обязательные разрешения необходимо предоставить на экране согласия, а от необязательных пользователь может отказаться.

Получите доступные scope через API. Используйте scope ID при создании клиента через API.

curl "https://api.cloudflare.com/client/v4/oauth/scopes" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer $API_TOKEN"

Чтобы пометить области доступа как необязательные, включите их в optional_scopes запроса. Это должно быть подмножеством scopes для клиента. Пользователь может отклонить необязательные области доступа во время авторизации.

Поддерживаемые потоки OAuth

OAuth-клиенты Cloudflare поддерживают Authorization Code Flow протокола OAuth 2.0.

Cloudflare не поддерживает типы авторизации OAuth Client Credentials, Implicit, Resource Owner Password Credentials, Device Authorization и другие для сторонних клиентов.

Выберите сценарий

Используйте следующие рекомендации, чтобы выбрать поток OAuth:

Тип клиента	Поток	Аутентификация конечной точки токена	PKCE
Серверное веб-приложение или бэкенд-сервис	Authorization Code с client secret	`client_secret_basic` или `client_secret_post`	Необязательно/не требуется
Браузерное, мобильное, настольное приложение или приложение командной строки (CLI)	Authorization Code with PKCE	`none`	Обязательно, `S256`

Секрет клиента

Authorization Code flow предназначен для защищённых серверных приложений, способных обеспечить сохранность client secret.

Когда использовать: Ваш OAuth-клиент представляет собой серверное веб-приложение или бэкенд-сервис.
Как это работает: Ваш клиент перенаправляет пользователя на страницу авторизации. После авторизации Cloudflare возвращает код авторизации вашему бэкенду. Бэкенд обменивает код и секрет клиента на токен доступа.
Примечание по безопасности: Никогда не раскрывайте секрет клиента в клиентском коде и не встраивайте его в бинарные файлы мобильных клиентов.

PKCE

Proof Key for Code Exchange (PKCE) расширяет Authorization Code flow для публичных клиентов, например мобильных или одностраничных приложений, где невозможно безопасно хранить секрет клиента.

Когда использовать: Ваш OAuth-клиент представляет собой одностраничное, мобильное, настольное или CLI-приложение.
Как это работает: Ваше приложение генерирует уникальные code verifier и code challenge для каждого запроса на вход вместо использования статического секрета клиента.
Примечание по безопасности: Клиентам, использующим PKCE, секрет клиента не требуется.

Приватные и публичные клиенты

Новые клиенты OAuth по умолчанию создаются с приватной видимостью. Авторизовать приватные клиенты могут только участники родительской учетной записи Cloudflare. Публичные клиенты допускают авторизацию любым пользователем Cloudflare.

Прежде чем сделать клиент публичным, выполните необходимые действия и заполните обязательные поля.

Обязательные поля

Имя клиента
Логотип
URL клиента
Области действия

Обязательные действия

OAuth-клиенты должны пройти подтверждение домена для URL-адреса клиента, прежде чем они смогут быть опубликованы.

Сделать клиента публичным

Перейдите в Manage Account > OAuth-клиенты.
Откройте меню действий для своего клиента.
Выберите Изменение видимости.

Перейдите в OAuth-клиенты ↗

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients/$CLIENT_ID" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer $API_TOKEN" \
	-d '{ "visibility": "public" }'

Проверка владения доменом URL клиента

Прежде чем клиент сможет стать общедоступным, Cloudflare требует подтверждения владения доменом URL клиента. Если ваш клиент предназначен только для частного использования участниками аккаунта, подтверждение владения доменом не требуется.

Скопируйте код подтверждения и создайте TXT запись в конфигурации DNS с этим значением. Запись должна включать весь текст, в том числе cloudflare_oauth_client_publisher= префикс.

Cloudflare опрашивает эту DNS-запись до тех пор, пока она не будет найдена, или пока не истечет двухдневный таймаут запроса.

Перезапустить проверку

Если время ожидания процесса проверки истекло, выберите Перезапустить проверку в меню действий клиента.

Чтобы перезапустить проверку, которая завершилась ошибкой или истекла по тайм-ауту, отправьте PATCH запрос с существующим client_uri без изменений.

curl -X PATCH "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients/$CLIENT_ID" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer $API_TOKEN" \
	-d '{ "client_uri": "https://example.com" }'

Ротация клиентских секретов

У каждого клиента может быть два секрета. Это позволяет создать новый секрет, обновить клиент для использования нового секрета и удалить старый секрет.

Перейдите в Manage Account > OAuth-клиенты.
Откройте меню действий для своего клиента.
Выберите Ротация клиентского секрета.
Сохраните новый секрет в надежном месте.
После того как ваш клиент начнёт использовать новый секрет, удалите старый.

Перейдите в OAuth-клиенты ↗

Чтобы узнать, находится ли клиент в процессе смены секрета, найдите has_rotated_secret в GET ответ. Если значение равно true, удалите старый секрет, прежде чем создавать новый.

Создание нового секрета

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients/$CLIENT_ID/rotate_secret" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer $API_TOKEN"

Удалите старый секрет

curl -X DELETE "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/oauth_clients/$CLIENT_ID/rotate_secret" \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer $API_TOKEN"