Введение в OAuth 2

Введение

Это информационное руководство предназначено для разработчиков приложений и содержит обзор ролей OAuth 2, типов предоставления авторизации, вариантов использования и потоков.

Роли OAuth

OAuth определяет четыре роли:

С точки зрения разработчика приложения, API сервиса выполняет роль как ресурса, так и сервера авторизации. Мы будем называть обе эти роли вместе взятыми как роль службы или API.

Поток абстрактного протокола

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

Вот более подробное объяснение шагов на диаграмме:

Фактический ход этого процесса будет отличаться в зависимости от используемого типа предоставления авторизации, но это общая идея. Мы рассмотрим различные типы грантов в следующем разделе.

Регистрация заявки

В описанном ранее потоке абстрактного протокола первые четыре шага охватывают получение разрешения на авторизацию и токена доступа. Тип предоставления авторизации зависит от метода, используемого приложением для запроса авторизации, и типов предоставления, поддерживаемых API. O Auth 2 определяет три основных типа грантов, каждый из которых полезен в разных случаях:

Предупреждение. Платформа OAuth определяет два дополнительных типа предоставления: тип неявного потока и тип предоставления пароля. Однако эти типы грантов считаются небезопасными и больше не рекомендуются к использованию.

Код авторизации

Теперь опишем поток кода авторизации:

Шаг 1 — Ссылка на код авторизации

Вот объяснение компонентов этого примера ссылки:

Шаг 2 — Пользователь авторизует приложение

Шаг 3 — Приложение получает код авторизации

Приложение запрашивает токен доступа из API, передавая код авторизации вместе с данными аутентификации, включая секрет клиента, в конечную точку токена API. Вот пример POST-запроса к конечной точке токена DigitalOcean:

Если авторизация действительна, API отправит приложению ответ, содержащий токен доступа (и, при необходимости, токен обновления). Весь ответ будет выглядеть примерно так:

Примечание относительно ключа подтверждения для обмена кодами

Если публичный клиент использует тип предоставления кода авторизации, есть вероятность, что код авторизации может быть перехвачен. Ключ подтверждения для обмена кодами (или PKCE, произносится как «пикси») — это расширение потока кода авторизации, помогающее смягчить атаки такого типа.

Расширение PKCE предполагает, что клиент создает и записывает секретный ключ — известный как верификатор кода — для каждого запроса авторизации. Затем клиент преобразует верификатор кода в вызов кода, а затем отправляет этот вызов кода и метод преобразования в конечную точку авторизации в том же запросе авторизации.

Конечная точка авторизации записывает запрос кода и метод преобразования и отвечает кодом авторизации, как описано ранее. Затем клиент отправляет запрос токена доступа, который включает первоначально сгенерированный им верификатор кода.

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

Учетные данные клиента

Тип предоставления учетных данных клиента предоставляет приложению способ доступа к собственной учетной записи службы. Примеры того, когда это может быть полезно, включают, если приложение хочет обновить свое зарегистрированное описание или URI перенаправления или получить доступ к другим данным, хранящимся в его учетной записи службы, через API.

Поток учетных данных клиента

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

Примечание. В настоящее время DigitalOcean не поддерживает тип предоставления учетных данных клиента, поэтому ссылка указывает на воображаемый сервер авторизации по адресу oauth.example.com.

Код устройства

Вот как может выглядеть пример ответа от конечной точки авторизации устройства:

Обратите внимание, что код устройства также может быть QR-кодом, который считыватель может отсканировать на мобильном устройстве.

Примечание. Опять же, DigitalOcean в настоящее время не поддерживает тип предоставления кода устройства, поэтому ссылка в этом примере указывает на воображаемый сервер авторизации по адресу oauth.example.com.

Вот пример запроса API с использованием curl. Note that it includes the access token:

curl -X POST -H «Authorization: Bearer ACCESS_TOKEN»»https://api.digitalocean.com/v2/$OBJECT»

Assuming the access token is valid, the API will process the request according to its API specifications. If the access token is expired or otherwise invalid, the API will return an invalid_request error.

Refresh Token Flow

After an access token expires, using it to make a request from the API will result in an Invalid Token Error. At this point, if a refresh token was included when the original access token was issued, it can be used to request a fresh access token from the authorization server.

Here is an example POST request, using a refresh token to obtain a new access token:

Введение

Эта статья предназначена для разработчиков приложений и предоставляет обзор ролей, типов авторизации и типичных сценариев использования OAuth 2.

Начнём с ролей OAuth!

Роли OAuth

OAuth определяет четыре роли:

Далее мы рассмотрим каждую из ролей.

Владелец ресурса

Владельцем ресурса является пользователь, который авторизует приложение для доступа к своему аккаунту. Доступ приложения к пользовательскому аккаунту ограничен “областью видимости” (scope) предоставленных прав авторизации (например, доступ на чтение или запись).

Сервер ресурсов / авторизации

Сервер ресурсов непосредственно хранит защищённые данные аккаунтов пользователей, а авторизационный сервер проверяет подлинность информации, предоставленной пользователем, а затем создаёт авторизационные токены для приложения, с помощью которых приложение будет осуществлять доступ к пользовательским данным.

С точки зрения разработчика приложения API сервиса одновременно выполняет и роль сервера ресурсов и роль сервера авторизации. Далее мы будем считать эти две роли одной, и называть её Сервис или API.

Приложение

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

Абстрактное описание протокола

Теперь, когда у нас есть представление о ролях, используемых в OAuth, рассмотрим диаграмму их взаимодействия друг с другом.

Рассмотрим описание последовательности шагов на этой диаграмме:

Фактический порядок шагов описанного процесса может отличаться в зависимости от используемого типа разрешения на авторизацию, но в целом процесс будет выглядеть описанным образом. Далее мы рассмотрим различные типы разрешений на авторизацию.

Регистрация приложения

Перед тем, как начать использовать OAuth в вашем приложении, вам необходимо зарегистрировать своё приложения в сервисе. Это делается путём регистрации в разделе “developer” или “API” сайта сервиса, где вам необходимо предоставить следующую информацию (возможно, включая некоторые детали о вашем приложении):

Redirect URL — это URL, на который сервис будет перенаправлять пользователя после авторизации (или отказа в авторизации) вашего приложения.

Идентификатор клиента и секрет клиента

После регистрации приложения сервис создаст учётные данные клиента — идентификатор клиента (client ID) и секрет клиента (client secret). Идентификатор клиента представляет собой публично доступную строку, которая используется API сервиса для идентификации приложения, а также используется для создания авторизационных URL для пользователей. Секрет клиента используется для аутентификации подлинности приложения для API сервиса, когда приложение запрашивает доступ к аккаунту пользователя. Секрет клиента должен быть известен только приложению и API.

Разрешение на авторизацию

В абстрактном описании протокола выше первые четыре шага касаются вопросов создания разрешения на авторизацию и токена доступа. Тип разрешения на авторизацию зависит от используемого приложением метода запроса авторизации, а также от того, какие типы разрешения поддерживаются со стороны API. O Auth 2 определяет четыре разных типа, каждый из которых полезен в определённых ситуациях:

Далее мы рассмотрим эти типы разрешения на авторизацию, примеры их использования.

Тип разрешения на авторизацию

Опишем процесс на диаграмме:

Ссылка с кодом авторизации

Сначала пользователю предоставляется ссылка следующего вида:

Рассмотрим компоненты ссылки:

Пользователь авторизует приложение

Если пользователь выбирает “Авторизовать приложение”, сервис перенаправляет пользовательский агент (браузер) по URL перенаправления (redirect URL), который был задан на этапе регистрации клиента (вместе с кодом авторизации). Ссылка будет выглядеть похожим образом (в данном примере приложение называется “dropletbook.com”):

Приложение запрашивает токен доступа

Приложение запрашивает токен доступа у API путём отправки авторизационного кода и аутентификационной информации (включая секрет клиента) сервису. Ниже представлен пример POST-запроса для получения токена DigitalOcean:

Приложение получает токен доступа

Если авторизация прошла успешно, API возвращает токен доступа (а также, опционально, токен для обновления токена доступа — refresh token). Весь ответ сервера может выглядеть следующим образом:

,,:2592000,,,:100101,:»Mark E. Mark»,

Теперь приложение авторизовано! Оно может использовать токен для доступа к пользовательскому аккаунту через API сервиса с заданными ограничениями доступа до тех пор, пока не истечёт срок действия токена или токен не будет отозван. Если был создан токен для обновления токена доступа, он может быть использован для получения новых токенов доступа, когда истечёт срок действия старого токена.

Неявный тип разрешения на авторизацию используется мобильными и веб-приложениями (приложениями, которые работают в веб-браузере), где конфиденциальность секрета клиента не может быть гарантирована. Неявный тип разрешения также основан на перенаправлении пользовательского агента, при этом токен доступа передаётся пользовательскому агенту для дальнейшей передачи приложению. Это, в свою очередь, делает токен доступным пользователю и другим приложениям на устройстве пользователя. Также при этом типе разрешения на авторизацию не осуществляется аутентификация подлинности приложения, а сам процесс полагается на URL перенаправления (зарегистрированный ранее в сервисе).

Неявный тип разрешения на авторизацию не поддерживает токены обновления токена доступа (refresh tokens).

Процесс выглядит следующим образом: приложение просит пользователя авторизовать себя, затем сервер авторизации передаёт токен доступа к пользовательскому агенту, который передаёт токен приложению. Далее мы опишем процесс в деталях.

Ссылка для неявной авторизации

При неявном типа разрешения на авторизацию пользователю предоставляется ссылка, запрашивающая токен у API. Эта ссылка выглядит почти так же, как ссылка для предыдущего способа (с кодом авторизации), за исключением того, что запрашивается токен вместо кода (обратите внимание на response type “token”):

Если пользователь выбирает “Авторизовать приложение”, сервис перенаправляет пользовательский агент по URI пренправления приложения и включает в URI фрагмент, содержащий токен доступа. Это выглядит примерно вот так:

Пользовательский агент следует по URI перенаправления

Пользовательский агент следует по URI перенаправления, сохраняя при этом токен доступа.

Приложение выполняет скрипт извлечения токена доступа

Приложение возвращает веб-страницу, которая содержит скрипт для извлечения токен доступа из полного URI перенаправления, сохранённого пользовательским агентом.

Токен доступа передаётся приложению

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

Учётные данные владельца ресурса

При этом типе разрешения на авторизацию пользователь предоставляет приложению напрямую свои авторизационные данные в сервисе (имя пользователя и пароль). Приложение, в свою очередь, использует полученные учётные данные пользователя для получения токена доступа от сервиса. Этот тип разрешения на авторизацию должен использоваться только в том случае, когда другие варианты не доступны. Кроме того, этот тип разрешения стоит использовать только в случае, когда приложение пользуется доверием пользователя (например, является частью самого сервиса, или операционной системы пользователя).

Процесс с учётными данными владельца ресурса

После того, как пользователь передаст свои учётные данные приложению, приложение запросит токен доступа у авторизационного сервера. Пример POST-запроса может выглядеть следующим образом:

Если учётные данные корректны, сервер авторизации вернёт токен доступа приложению. Теперь приложение авторизовано!

Внимание: DigitalOcean в настоящее время не поддерживает тип разрешения на авторизацию с использованием учётных данных владельца ресурса, поэтому ссылка выше ведёт на воображаемый авторизационный сервер “oauth.example.com”.

Тип разрешения на авторизацию с использованием учётных данных клиента позволяет приложению осуществлять доступ к своему собственному аккаунту сервиса. Это может быть полезно, например, когда приложение хочет обновить собственную регистрационную информацию на сервисе или URI перенаправления, или же осуществлить доступ к другой информации, хранимой в аккаунте приложения на сервисе, через API сервиса.

Процесс с учётными данными клиента

Приложение запрашивает токен доступа путём отправки своих учётных данных, своего идентификатора клиента и секрета клиента авторизационному серверу. Пример POST-запроса может выглядеть следующим образом:

Если учётные данные клиента корректны, авторизационный сервер вернёт токен доступа для приложения. Теперь приложение авторизовано для использования собственного аккаунта!

Внимание: DigitalOcean в настоящее время не поддерживает тип разрешения на авторизацию с использованием учётных данных клиента, поэтому ссылка выше ведёт на воображаемый авторизационный сервер “oauth.example.com”.

Пример использования токена доступа

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

Ниже представлен пример запроса к API с использованием curl. Обратите внимание, что он содержит токен доступа:

POST «Authorization: Bearer ACCESS_TOKEN»»https://api.digitalocean.com/v2/»

Если токен доступа валиден, API обработает полученный запрос. Если срок действия токена доступа истёк или токен некорректен, API вернёт ошибку “invalid_request”.

Обновление токена доступа

После истечения срока действия токена доступа все запросы к API с его использованием будут возвращать ошибку “Invalid Token Error”. Если при создании токена доступа был создан и токен для обновления токена доступа (refresh token), последний может быть использован для получения нового токена доступа от авторизационного сервера.

Ниже представлен пример POST-запроса, использующего токен для обновления токена доступа для получения нового токена доступа:

Заключение

На этом мы завершаем наш обзор OAuth 2. Теперь у вас есть общее представление о том, как работает OAuth 2, а также о том, когда и как использовать существующие типы разрешения на авторизацию.

Request Parameters

response_type will be set to code, indicating that the application expects to receive an authorization code if successful.

Client_id

The client_id is the public identifier for the app.

Redirect_uri (optional)

The redirect_uri is not required by the spec, but your service should require it. This URL must match one of the URLs the developer registered when creating the application, and the authorization server should reject the request if it does not match.

Scope (optional)

The state parameter is used by the application to store request-specific data and/or prevent CSRF attacks. The authorization server must return the unmodified state value back to the application.

PKCE

If the authorization server supports the PKCE extension (described in PKCE) then the code_challenge and code_challenge_method parameters will also be present. These must be remembered by the authorization server between issuing the authorization code and issuing the access token.

Verifying the Authorization Request

The authorization server must first verify that the client_id in the request corresponds to a valid application.

If your server allows applications to register more than one redirect URL, then there are two steps to validating the redirect URL. If the request contains a redirect_uri parameter, the server must confirm it is a valid redirect URL for this application. If there is no redirect_uri parameter in the request, and only one URL was registered, the server uses the redirect URL that was previously registered. Otherwise, if no redirect URL is in the request, and no redirect URL has been registered, this is an error.

Неверный URL-адрес перенаправления

Если в запросе отсутствует параметр response_type или значение этого параметра отличается от кода или токена, сервер может вернуть ошибку invalid_request.

Поскольку сервер авторизации может потребовать от клиентов указать, являются ли они общедоступными или конфиденциальными, он может отклонять запросы на авторизацию, которые не разрешены. Например, если клиент указал, что он является конфиденциальным клиентом, сервер может отклонить запрос, использующий тип предоставления токена. При отказе по этой причине используйте код ошибки author_client.

Сервер авторизации должен отклонить запрос, если есть значения области, которые он не распознает. В этом случае сервер может перенаправить на URL-адрес обратного вызова с кодом ошибки invalid_scope.

Серверу авторизации необходимо сохранить значение «состояние» (и значения PKCE) для этого запроса, чтобы включить его в ответ авторизации. Сервер не должен изменять или делать какие-либо предположения о том, что содержит значение состояния, поскольку это делается исключительно в интересах клиента.

Ответ кода авторизации

Срок действия кода авторизации должен истечь вскоре после его выдачи. Спецификация OAuth 2.0 рекомендует максимальное время жизни 10 минут, но на практике большинство служб устанавливают срок действия намного короче, около 30-60 секунд. Сам код авторизации может быть любой длины, но длина кодов должна быть задокументирована.

Поскольку коды авторизации должны быть недолговечными и одноразовыми, вы можете реализовать их как токены с самокодированием. С помощью этого метода вы можете избежать хранения кодов авторизации в базе данных, а вместо этого закодировать всю необходимую информацию в самом коде авторизации. Вы можете использовать либо встроенную библиотеку шифрования вашей серверной среды, либо стандарт, такой как веб-подпись JSON (JWS). Однако, поскольку этот код авторизации предназначен только для использования сервером авторизации, часто бывает проще реализовать их в виде коротких строк, хранящихся в кэше на стороне сервера, доступном для конечной точки авторизации и конечной точки токена.

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

Государство

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

HTTP/1.1 302 Найдено
Расположение: https://example-app.com/redirect?code=g0ZGZmNjVmOWI&state=dkZmYxMzE2

Ответ типа неявного гранта

С неявным предоставлением (response_type=token) сервер авторизации немедленно генерирует токен доступа и перенаправляет на URL-адрес обратного вызова с токеном и другими атрибутами токена доступа во фрагменте.

HTTP/1.1 302 Найдено
Расположение: https://example-app.com/redirect#access_token=MyMzFjNTk2NTk4ZTYyZGI3.
&состояние=dkZmYxMzE2
&token_type=Носитель
&expires_in=86400

Как видите, это намного опаснее, чем выдача временного одноразового кода авторизации. Поскольку существует гораздо больше способов, которыми злоумышленник может украсть данные из HTTP-перенаправления по сравнению с перехватом HTTPS-запроса, использование этого варианта гораздо более рискованно по сравнению с потоком кода авторизации.

С точки зрения сервера авторизации, в тот момент, когда он создает токен доступа и отправляет HTTP-перенаправление, он не может узнать, было ли перенаправление успешным и нужное ли приложение получило токен доступа. Это своего рода подбрасывание токена доступа в воздух и скрещивание пальцев, чтобы приложение его поймало. Это отличается от метода кода авторизации, где, хотя сервер авторизации не может гарантировать, что код авторизации не был украден, он может, по крайней мере, предотвратить использование украденного кода авторизации, требуя секрет клиента или верификатор кода PKCE. . Это обеспечивает гораздо более высокий уровень безопасности, поскольку теперь сервер авторизации может быть более уверенным в том, что он не отдаст токены доступа злоумышленникам.

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

Если запрос содержал параметр состояния, ответ об ошибке также должен включать точное значение из запроса. Клиент может использовать это, чтобы связать этот ответ с первоначальным запросом.