Общие сведения

Маркеры доступа (access tokens) из соображений безопасности имеют короткий срок действия, поэтому, чтобы получить долговременный доступ к ресурсам, клиентское приложение (далее клиент) может использовать специальные маркеры обновления (refresh tokens).

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

Пример

POST /STS/oauth/token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

В запросе клиент указывает свои учетные данные в заголовке Authorization, а также тип разрешения refresh_token в параметр grant_type и значения маркера обновления в параметре refresh_roken.

В ответ сервер возвращает следующие данные:

  • access_token - новый маркер доступа.
  • expires_in - время жизни маркера доступа в секундах.
  • token_type - тип маркера доступа (сейчас всегда Bearer).
  • refresh_token - маркер обновления (возможно новый).
  • refresh_token_expires_in - время жизни маркера обновления.

Пример

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token":"eyJ0eXAiOiJKV1Q ... LnS1sAunDSE1hh3A5n8W7lhPSM4z_VA",
    "expires_in":300,
    "token_type":"Bearer",
    "refresh_token": "774fae55a7e64c8238c35695c4198198",
    "refresh_token_expires_in":1800
}

Следует обратить внимание, что параметр refresh_token_expires_in не специфицирован в RFC, но используется многими центрами идентификациями (ADFS, Duende Identity Server), так как позволяет существенно упростить логику работы клиента.

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

Set-DssIdsClient -ClientId AllowedFlows RefreshToken

Для получения первого маркера обновления в запросе (вне зависимости от сценарии) необходимо указать область использования (scope) offline_access.

Пример

POST /STS/oauth/token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

username=ivanov&password=&grant_type=password&resource=urn%3Acryptopro%3Adss%3Asignserver%3ASignServer&scope=dss%20offline_access

Типы маркеров обновления

Маркеры обновления различаются

  • По типу использования: одноразовые (OneTime) и переиспользуемые (ReUse).
  • По типу истечения: с абсолютным истечением и со скользящим истечением.

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

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

Тип использования задается в настройках клиентов следующей командой:

Set-DssIdsClient -RefreshTokenTokenUsage ReUse

или

Set-DssIdsClient -RefreshTokenTokenUsage OneTime

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

Маркеры обновления с абсолютным истечением имеют фиксированный срок жизни, задаваемый в секундах параметром -RefreshTokenLifetime, тип истечения указывается в параметре -RefreshTokenExpirationType

Set-DssIdsClient -RefreshTokenTokenLifetime 3000 -RefreshTokenExpirationType Absolute

Маркеры обновления со скользящим истечением позволяют реализовать более гибкий сценарий использования. В данном режиме у маркера появляется два срока жизни скользящий и абсолютный. Абсолютный срок имеет тот же смысл, что и в режиме Absolute: после его истечения маркер использовать не получится, скользящий срок используется для организации сессии в клиентском приложении. Изначально срок действия маркера устанавливается равным скользящему сроку, но если в течение скользящего срока маркер обновления будет использован (то есть произойдет его обмен на маркер доступа), то его жизнь продлевается еще на один скользящий срок, таких продлений может быть много, но суммарное время жизни не может превысить абсолютный срок истечения. Таким образом, в клиентском приложении можно организовать сессии: скользящий срок - это максимальное время бездействия пользователя, по истечению которого требуется повторная аутентификация.

Пример

Пусть абсолютный срок равен 6 часам, скользящий срок равен 1 часу. При первом получении маркера обновления в 12:00 его время жизни составит 1 час, если в течение этого часа маркер не будет использован, то в 13:00 он истечет, если же его используют в 12:30, то срок жизни продлится на 1 час, до 13:30. При этом, если маркер будет использован, например, в 17:30, то его срок действия составит 30 минут (вместо 1 часа), так как суммарное время жизни не может превыщать 6 часов (12:00 + 6ч = 18:00).

Для настройки типа истечения используются два параметра -RefreshTokenExpirationType со значением Sliding и -RefreshTokenSlidingLifetimeSeconds.

Set-DssIdsClient -RefreshTokenTokenLifetime 3000 -RefreshTokenExpirationType Sliding -RefreshTokenSlidingLifetimeSeconds 1000

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

Пример

Для клиента настроены одноразовые маркеры с абсолютным истечением 1 час. Рассмотрим возможный пример цепочек маркеров обновления и значения соответствующих refresh_token_expires_in:

  • Первое получение: refresh_token_expires_in = 3600
  • Обновление 1 (через 15 минут от получения): refresh_token_expires_in = 2700
  • Обновление 2 (через 30 минут от Обновления 1): refresh_token_expires_in = 900
  • Обновление 3 (через 10 минут от Обновления 2): refresh_token_expires_in = 300
  • Обновление 4 (через 10 минут от Обновления 3): ошибка inavlid_grant, так как срок действия маркера истек.

Отзыв маркеров обновления

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

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

Отзыв маркеров обновления осуществляется различными способами:

  • Через личный кабинет пользователя (можно отозвать маркеры, выданные различным клиентам) и оператора (можно отозвать только целиком все выданные маркеры).
  • Через API oauth/revocation конечной точки отзыва RFC7009.
  • Через API UMS по управлению разрешениями пользователя.

Рассмотрим каждый из способов отдельно.

Управление разрешениями в веб-интерфейсе

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

В личном кабинете оператора имеется возможность отозвать все выданные пользователем разрешения.

Отзыв разрешения через конечную отзыва маркеров

API oauth/revocation реализует, описанный в RFC7009 метод отзыва маркеров. Для отзыва маркера обновления неоходимо выполнить следующий запрос:

POST /STS/revocation HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token

В запросе клиент указывает свои учетные данные в заголовке Authorization. В параметр token передается значение маркера обновления, который требуется отозвать, в token_type_hint следует указать серверу тип отзываемого маркера - refresh_roken.

В случае успешного отзыва сервер вернет HTTP 200 OK.

Отзыв разрешений через API UMS

Сервис управления пользователями также позволяет работать с разрешиниями.

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

POST /STS/ums/user/{id}/grants/revoke HTTP/1.1
Host: server.example.com

здесь id - идентификатор пользователя.

Отзыв разрешений через API SelfUMS

Сервис самоуправления позволяет получить информацию о выданных разрешениях пользователя через запрос:

GET /STS/self/grants HTTP/1.1
Host: server.example.com
Content-Type: application/json
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW

В ответ сервис возвращает список разршений, выданных данным пользователем.

HTTP/1.1 200 OK
Content-Type: application/json
[{
    "Type":"RefreshToken",
    "CreatedAt":300,
    "ExpiresAt":"301",
    "ClientId": "774fae55a7e64c8238c35695c4198198",
    "ClientName":"test",
    "ClientDescription": "test"
}]

Для отзыва разрешения используется следующий запрос

POST /STS/self/grants/revoke HTTP/1.1
Host: server.example.com
Content-Type: application/json
Authorization: Bearer czZCaGRSa3F0MzpnWDFmQmF0M2JW

{
    "ClientId": "client-id",
    "GrantType": "RefreshToken"
}

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