#Идентификация [TOC]

##OAuth2 авторизация OAuth2-клиенты могут быть 2 типов:

• Конфиденциальные (server-hosted, когда client_secret может быть храниться и использоваться безопасно)
• Публичные (client-hosted, когда клиент не может обеспечить безопасного хранения и испольования секрета)

В случае "Публичных" клиентов проверки client_secret не осуществляется, но и прав доступно меньше.

Поддерживаются следующие grant_type:

• password (only for trusted!)
• implicit
• authorization_code
• client_credential (ex: Дарударовские полки)
• refresh_token

Grant type: Password

URI: POST ~/auth/oauth2/token

Данный тип авторизации доступен только "доверенным" клиентам.

Если вы используете данный тип авторизации, то обязательно проверяйте поле aud используемого JWT-токена перед отправкой запроса на сервер

Обязательные параметры:

Для "Публичных" клиентов параметр client_secret не используется.

Пример запроса

POST /auth/oauth2/token HTTP/1.1
HOST: api.darudar.org
content-type: application/x-www-form-urlencoded

grant_type=password&client_id=<client_id>&username=<login>&password=<password>

В успешной авторизации в ответе придёт access_token (JWT) для дальнейшей авторизации, а так-же refresh_token (JWT) для обновления доступа. Пример ответа представлен ниже:

#!json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": <access_token>,
  "refresh_token": <refresh_token> // <-- возвращается только для конфиденциальных клиентов (!)
}

Полученный access_token "живёт" expires_in секунд. Затем его можно обновить используя refresh_token (только для "конфиденциальных" клиентов).

Grant type: Implicit

URI: GET ~/auth/oauth2/authorize

Реализует доступ к токену авторизации для client-hosted приложений. В настоящий момент работает только для уже авторизованных пользователей(!).

Если вы используете данный тип авторизации, то обязательно проверяйте поле aud используемого JWT-токена перед отправкой запроса на сервер

Для данного типа авторизации есть возможность "обновить" access_token, для уже авторизованных пользователей добавив дополнительный параметр prompt со значением none (&prompt=none). В случае такого запроса или вернётся ответ с обновлённым токеном (если пользователь ещё авторизован) или же ошибка (если пользователь больше не авторизован).

Обязательные параметры:

Пример запроса

GET /auth/oauth2/token HTTP/1.1
HOST: api.darudar.org
content-type: application/x-www-form-urlencoded

response_type=token&client_id=<client_id>&redirect_uri=<APP_CALLBACK_URI>&state=<state-session-string>

В успешной авторизации будет произведён редирект на указанный урл с хеш-параметром в котором будет содержаться access_token (JWT) для дальнейшей авторизации

Пример ответа представлен ниже:

Redirect to: APP_CALLBACK_URI#access_token=<access_token>&state=<state>

Перед проверкой и использованием access_toekn следует обязательно проверить параметр state (!).

Grant type: Authorization Code

URI: GET ~/auth/oauth2/authorize

Если вы используете данный тип авторизации, то обязательно проверяйте поле aud используемого JWT-токена перед отправкой запроса на сервер

Обязательные параметры:

Для "Публичных" клиентов параметр client_secret не используется.

Пример запроса

GET /auth/oauth2/authorize HTTP/1.1
HOST: api.darudar.org
content-type: application/x-www-form-urlencoded

response_type=code&client_id=<client_id>&username=<login>&state=<state-session-string>

В успешной авторизации будет произведён редирект на указанный урл с параметром code.

Пример ответа:

Redirect to: APP_CALLBACK_URI?code=<code>&state=<state>

Перед выполнением следующего запроса требуется обязательно проверить параметр state для предотвращения подмены кода авторизации. (!) Затем следует выполнить следующий запрос:

Обязательные параметры:

Пример запроса

POST /auth/oauth2/token HTTP/1.1
HOST: api.darudar.org
content-type: application/x-www-form-urlencoded

grant_type=authorizatin_code&client_id=<client_id>&code=<code>

В успешном выполнении запроса в ответе придёт access_token (JWT) для дальнейшей авторизации, а так-же refresh_token (JWT) для обновления доступа. Пример ответа представлен ниже:

#!json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": <access_token>,
  "refresh_token": <refresh_token>
}

Полученный access_token "живёт" expires_in секунд. Затем его можно обновить используя refresh_token (только для "конфиденциальных" клиентов).

Grant type: Refresh Token

URI: POST ~/auth/oauth2/token/

Данный тип авторизации используется для получения нового access_token после его инвалидации.

Обязательные параметры:

Пример запроса:

POST /auth/oauth2/token HTTP/1.1
HOST: api.brutto.dev.darudar.com
content-type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=<client_id>&refresh_token=<refresh_token>

Пример ответа:

#!json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": <access_token>,
  "refresh_token": <refresh_token>
}

В ответе приходит стандартный JSON-объект с новыми актуальными авторизационными данными.

##Восстановление доступа к учетной записи

Для восстановления доступа необходимо чтобы в учётной записи был указан рабочий email-адрес или подтверждённый номер мобильного телефона (пока не реализовано).

Запрос на восстановление пароля

URI: POST ~/auth/recover/request

Пример запроса:

POST /auth/recover/request HTTP/1.1
Host: api.brutto.dev.darudar.com
Content-type: application/json

{"client": "<client-id>", "recover": "<login_or_email>"}

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

Пример ответа:

#!json
{
    "recover": "send"
}

Подтвежрдение смены пароля

URI: POST ~/auth/recover/submit/<code>

<code> обязательный параметр из полученного письма.

Пример запроса:

POST /auth/recover/submit/<code> HTTP/1.1
Host: api.brutto.dev.darudar.com
Content-type: application/json

{"password": "<pass-string>","password_confirm": "<pass-string>"}

Пример ответа:

#!json
{
    "recover": "ok"
}

Внешняя авторизация

URI: GET ~/auth/oauth2/external/go/<provider>

Данный endpoint запускает процедуру внешней авторизации (происходит редирект на авторизацию). Параметр<provider> является указателем на провайдера внешней авториазции. Доступны следующие:

• goog -- Гугл
• fb -- Фейсбук
• vk -- Вконтакте
• ok -- Одноклассника

Параметры (QUERY_PARAMS) аналогичные Implicit и Authorization Code (см. выше).

Пример запроса:

GET /auth/oauth2/external/go/goog?client_id=dd-oauth2.bbbd818b0d4f0eb33eb2cce8d217fa57666773ba&redirect_uri=https://app.darudar.org/auth/external&response_type=token HTTP/1.1
Host: api.brutto.dev.darudar.com
Content-type: application/json

При успешном завершении авторизации произодёт редирект с переданными изначально параметрами на endpoint /auth/oauth2/authorize?QUERY_PARAMS, откуда уже будет перенаправлен или сразу на APP_CALLBACK_URI (implicit) или на дальнейшую продеруду завершения авторизации (authorization_code).

При возникновении ошибки по причине отсутвия внешнего профиля в системе помимо стандартных параметров (error, message, hint) так же приходит параметр external_identity, который является JWT-токеном и содержит информацию о подключаемом профиле. Этот параметр можно использовать при регистрации.

Внутренняя авторизация (ограниченный доступ)

URI: POST ~/auth/sign-in

Даннйы метод используется только для внутренних (собственных) клиентов.

В зависимости от переданного Accept-заголовка данный метод возвращает в ответе или json-объект если это application/json с токеном доступа (см. выше) или делает редирект на ~/auth/authorize если это text/html.

Выход

URI: POST ~/auth/sign-out

Завершает пользовательскую сессию на сервере авторизации.

Пример запроса:

POST /auth/sign-out HTTP/1.1
Host: api.brutto.dev.darudar.com
Cache-Control: no-cache

Пример ответа:

#!json
{
    "signout": "ok"
}

Регистрация

Создание аккаунта

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

Пример запроса

POST /auth/sign-up HTTP/1.1
Host: api.brutto.dev.darudar.com
Accept: application/json
Content-Type: application/json

{
  "client": "<client-id>",
  "email": "my-email@example.com",
  "name": "Антон Карапуль",
  "password": "<password>",
  "rules_accepted": 1,
  "external_identity": <token>
}

Пример ответа

#!json
{
    "signup": "send_activation" <-- или 'ok', если активации не требуется
}

В зависимости от переданного Accept-заголовка данный метод возвращает в ответе или json-объект если это application/json с токеном доступа (см. выше) или делает редирект на ~/auth/sign-in если это text/html.

Активация аккаунта

URI: POST ~/auth/activate/<token>

Активирует профиль для которого был выпушен <token>. Выпущенный токен валиден в течение 30 дней с момента выпуска.

Пример запроса

POST /auth/activate/<token> HTTP/1.1
Host: api.brutto.dev.darudar.com

Пример ответа

#!json
{
    "activate": "ok"
}

Внешняя регистрация

Внешняя регистрация -- это регистрация при помощи внешних сервисов авторизации. Она осуществляется через последовательный вызов метода "внешней авторизации" для получения токена-внешнего-профиля (external_identity) и последующим вызова метода "регистрации" с передачей данного дополнительного параметра external_identity.