OAuth 2.0

OAuth 2.0 - протокол авторизации предоставляющей возможность для third-party приложений получить ограниченный доступ к сервису по HTTP.

note

Abstract

The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849.

Роли определенные в протоколе OAuth

• resource owner (владелец ресурса)

Авторизует (разрешает) доступ клиента к ресурсу.

• resource server (сервер ресурсов, API предоставляющее доступ к ресурсу / действию)

Предоставляет доступ к ресурсу. Проверяет наличие разрешения (авторизации).

• client (клиент)

Приложение, сервис, клиент запрашивающий доступ к ресурсу/действию.

• authorization server (сервер авторизации)

Система/сервис выдает токен (маркер), который принимается resource server как разрешение на выполнение действия.

Flow

1) client -> resource owner

Клиент обращается к владельцу ресурса для получения разрешения на запрос к ресурсу. Владелец выдает клиенту "authorization grant".

authorization grant

authorization grant (credential/полномочия) - это маркер разрешающий клиенту получить доступ к ресурсу. Далее клиент должен обменять authorization grant на токен доступа к ресурсу.

Резрешение владельча ресурса может быть следующих типов:

Какой grant использовать:

authorization code

Вместо того, чтобы запрашивать авторизацию непосредственно у владельца ресурса, клиент перенаправляет пользователя(владельца ресурса) на сервер авторизации.

Сервер авторизации проверяет подлинность пользователя (аутентифицирует пользователя), подтверждает вледение ресурсом и запрашивает авторизацию ресурса для клиента.

info

Поскольку владелец ресурса проходит аутентификацию только на сервере авторизации, учетные данные владельца ресурса никогда не передаются клиенту.

Сервер авторизации возвращает / передает клиенту код авторизации, который долее может быть обменен на Access Token.

Proof Key for Code Exchange. PKCE

PKCE - расширение для authorization code flow. Позволяет предотвратить атаки CSRF и authorization code injection.

info

PKCE is not a form of client authentication, and PKCE is not a replacement for a client secret or other client authentication. PKCE is recommended even if a client is using a client secret or other form of client authentication like private_key_jwt.

PKCE - позволяет избежать атак направленных на перехват authorization code. Добавляется code_verifier, который передается на сервер при аутентификации (Authorization Endpoint), а также в Token Endpoint при обмене authorization code на access code. Перехвата authorization code теперь не достаточно, так как злоумышленник должен знать code_verifier.

implicit

warning

It is not recommended to use the implicit flow (and some servers prohibit this flow entirely) due to the inherent risks of returning access tokens in an HTTP redirect without any confirmation that it has been received by the client.

Упрощенный "authorization code" flow, для браузеров.

Вместо authorization code выпускается сразу access token. Токен будет передан в браузер и тот сразу может выполнять запросы к ресурсу.

info

In the implicit flow, instead of issuing the client an authorization code, the client is issued an access token directly (as the result of the resource owner authorization).

При выпуске access token не выполняется аутентификация улиента. "client identity" может быть подтверждена по redirection URI, который используется для доставки токена.

resource owner password credentials

warning

The Password grant type is a legacy way to exchange a user's credentials for an access token. Because the client application has to collect the user's password and send it to the authorization server, it is not recommended that this grant be used at all anymore.

Username/password могут быть использованы как authorization grant для получения access token.

Лучше использовать только с доверенными клиентами, когда клиент - это часть системы или нет никаких других способов использовать authorization code.

Предполагает прямой доступ клиента к credentials владельца ресурса.

Клиент должен хранить credentials владельча ресурса на своей стороне.

client credentials

Учетные данные клиента (или другие формы аутентификации клиента) могут использоваться в качестве предоставления авторизации, когда область авторизации ограничена защищенными ресурсами, находящимися под контролем клиента, или защищенными ресурсами, ранее согласованными с авторизацией. сервер.

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

Refresh Token

Refresh Token также является authorization grant так как по нему можно получить новый Access Token и опционально новый Refresh Token в Token Endpoint.

Device Authorization Grant

Используется для систем без браузера или устройств с ограниченими на ввод. Выполняется обмен device code на access token.

Взаимодействие:

• Клиент (device) вызывает сервер авторизации и передает ему client identifier
• сервер авторизации выдает для устройства device code (authorization grant), User Code, Verification URI.

2) client -> authorization server

Клиент обращается к серверу авторизации и предьявляет authorization grant. Сервер авторизации проверяет authorization grant и выпускает/выдает "access token".

Опционально может выпускаться Refresh Token вместе с Access Token.

authorization grant помимо authorization code, device code может содержать дополнительные данные такие как:

• code_verifier для PKCE
• client identifier для device flow

etc...

Для implicit flow этого шага не существует так как Access Token выдается сразу.

Для device flow:

• Клиент (device) предлагает пользователю посетить Verification URI и подтвердить разрешения.
• Клиент (device) обращается в серверу авторизации, polling c (device code + client identifier).
• Пользователь (владельца ресурса) в бораузере подтверждает разрешения.
• После подтверждения пользователя (владельца ресурса) получает Access Token.

3) client -> resource owner

Клиент запрашивает ресурс / выполняет вызов сервиса у владельца ресурса, предьявляя access token. Владелец ресурса валидирует access token и выполняет запрошенное действие, если токен валиден.

В случае JWT access token проверка может сводиться к проверки целостности и выдавшей системы через проверку подпичи, проверки времени жизни токена.

Token's

Access Token

Используется для доступа к защищаемому ресурсу.

Токены включиют в себя описание scope/области разрешенного доступа и времени жизни (времени на которое предоставлен доступ).

Токен может представлять собой идентификатор для получения инфоримации для авторизации или модержать все информацию необходимую для авторизации в себе.

• id с которым делается вызов в стороннюю системы для получения данных для авторизации
• JWT со всем необходимым для авторизации

Refresh Token

Refresh Token - credentials используемый для получения Access Token.

Refresh Token - это строка представляющая authorization granted от владельца ресурса.

Выпускается (optional) вместе с Access Token сервером авторизации и используется клиентом для получения нового Access Token когда Access Token становится не действительным или истекает время его жизни.

Клиент должен хранить Refresh Token в защищенном хранилище.

Получение нового Access Token по Refresh Token

1. Клиент образается к серверу авторизации и передает ему Refresh Token
2. Сервер авторизации аутентифицирует клиента по Refresh Token и возвращает/передает клиенту новый Access Token. Опционально модет быть выдан новый Refresh Token.
3. Refresh Token становится невалидным

Регистрация

Для проведения авторизации/аутентификации клиентов сервер авторизации должен знать про них, клиенты долджны быть предварительно зарегистрированы.

Данные клиента:

• Тип клиента
• redirection URIs
• другая информация: application name, website, description, logo image, the acceptance of legal terms

Тип клиента

confidential

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

Для клиентов этого типа приянто использовать аутентификацию при доступе клиента к серверу авторизации. Аутентификация может быть выполнена по client_id & client_secret, любой http authentication method.

public

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

Endpoints

Для реализации протокола необходимо реализовать следующие методы:

Authorization endpoint

Используется клиентов для получения authorization grant от владельца ресурса через user-agent redirection.

Через Response Type клиент информарует сервер авторизации какой grant он хочет получить.

Redirection Endpoint - url для передачи authorization grant. Должен совпадать с укзанным(ми) при регистрации.

Token endpoint

Используется для получения клиентов Access Token по authorization grant.

Redirection endpoint

Реализуется на стороне клиента для получения authorization grant от сервера аутентификации.

Access Token Scope

Аuthorization и Token endpoints позволяют клиенту указать scope.

scope - список (list of space-delimited, case-sensitive strings) разрешений для токена.

warning

The authorization server MAY fully or partially ignore the scope requested by the client, based on the authorization server policy or the resource owner's instructions.

Links & Docs

The OAuth 2.0 Authorization Framework
OAuth 2.0
PKCE. Proof Key for Code Exchange
OAuth 2.0 Device Authorization Grant
A Guide To OAuth 2.0 Grants
OAuth 2.0 Security Best Current Practice