Эта документация перемещена в архив и не поддерживается.

Simple Web Token (SWT)

Обновлено: Июнь 2015 г.

Настоящий документ, выпущенный в 2009 г., разработан в качестве рекомендованного стандарта по Simple Web Token (SWT) для группы IETF. Хотя он не завершен и не является разделом справки, в нем приведены интересные сведения о формате и использовании маркеров SWT.

Версия 0.9.5.1, 4 ноября 2009 г.

Simple Web Token (SWT) предоставляет формат для передачи утверждения между двумя сторонами. Утверждения — это набор пар «имя-значение», закодированных в HTML-форме. Результирующая строка подтверждается SHA 256 HMAC с помощью общего ключа сторон.

  • Дик Хардт (Dick Hardt) (dick.hardt@microsoft.com), редактор

  • Ярон Голанд (Yaron Goland) (yarong@microsoft.com)

Эта спецификация доступна в рамках соглашения Open Web Foundation версии 0.9, которое можно найти по адресу [http://groups.google.com/group/open-web-board/web/owf-agreement-for-final-specs---pt-9-draft] [Примечание. Ожидается обновленный URL-адрес.]Подписанные копии соглашения Open Web Foundation Agreement версии 0.9 для данной спецификации находятся в [вставьте URI хранилища соглашений]. В них могут быть указаны дополнительные стороны. Ваше использование данной спецификации может подпадать под права прочих третьих лиц. ЭТА СПЕЦИФИКАЦИЯ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ». Участники (соавторы) явно отказываются от любых гарантий (явных, подразумеваемых или иных), включая подразумеваемые гарантии товарного состояния, патентной чистоты, соответствия конкретным целям или прав собственности, связанных со спецификацией. Всю ответственность за внедрение или иное использование спецификации несет исполнитель и пользователь спецификации. НИКАКАЯ СТОРОНА НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ НЕ НЕСЕТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ УБЫТКИ ИЛИ ЛЮБЫЕ КОСВЕННЫЕ, ОСОБЫЕ, СЛУЧАЙНЫЕ ИЛИ ОПОСРЕДОВАННЫЕ УБЫТКИ ВСЛЕДСТВИЕ ЛЮБЫХ ПРИЧИН В ОТНОШЕНИИ НАСТОЯЩЕЙ СПЕЦИФИКАЦИИ ИЛИ ЕГО УПРАВЛЯЮЩЕГО СОГЛАШЕНИЯ, ВСЛЕДСТВИЕ НАРУШЕНИЯ УСЛОВИЙ КОНТРАКТА, НАРУШЕНИЕ ЗАКОННЫХ ПРАВ (В ТОМ ЧИСЛЕ, ПО НЕБРЕЖНОСТИ) ИЛИ ПО ИНЫМ ПРИЧИНАМ, И НЕЗАВИСИМО ОТ ТОГО, ЗНАЛА ЛИ ДРУГАЯ СТОРОНА О ВОЗМОЖНОСТИ ТАКИХ УБЫТКОВ.

Простой веб-маркер (Simple Web Token, SWT) определяет компактный формат для передачи простых утверждений, которые в отформатированном виде могут быть включены в заголовок для протоколов, например HTTP. Простое утверждение может быть представлено как набор пар «имя-значение». Значения, закодированные в форме HTML, соответствуют поставленной целям, которые заключаются в предоставлении хорошо понятного и безопасного формата заголовков HTTP.

Так как маркеры SWT будут передавать важные сведения об идентификации и доступе, требуется предотвратить возможность несанкционированного доступа к ним. Поэтому мы представляем в SWT единственную обязательную пару «имя-значение» — HMACSHA256. Эта пара всегда является последней парой в SWT, а значением является SHA 256 HMAC других пар «имя-значение» в SWT.

Выбор других пар «имя-значение», используемых в SWT, выходит за рамки этой спецификации. С другой стороны, существует ряд условий и атрибутов, которые подтвердили свою функциональность в рамках различных платформ утверждения, а именно: издатель, аудитория и ExpiresOn. Хотя использование этих пар «имя значение» не является обязательным, мы определяем их в данном документе для упрощения взаимодействия.

И, наконец, ожидается, что целый ряд атрибутов будет создан сторонами, осуществляющими обмен SWT. Использование обратных DNS-имен позволяет упростить процесс создания имен атрибутов и исключить возникновение конфликтов имен. Кроме того, поддерживается использование URI в качестве имен. Имена, которые не являются ни обратными DNS-именами, ни URI, представляют собой закрытые имена, определенные соглашением между производителем и потребителем SWT, поэтому они могут быть причиной конфликтов. Имена, определенные в данной спецификации, являются зарезервированными.

Ключевые слова «необходимо» (MUST), «недопустимо» (MUST NOT), «требуется» (REQUIRED), «нужно» (SHALL), «не нужно» (SHALL NOT), «следует» (SHOULD), «не следует» (SHOULD NOT), «рекомендуется» (RECOMMENDED), «возможно» (MAY), «необязательно» (OPTIONAL) в данном документе должны интерпретироваться в соответствии с документом [RFC2119] (Bradner B., «Key words for use in RFCs to Indicate Requirement Levels»). В примерах имен доменов используется [RFC2606] (Eastlake D. и A. Panitz, «Reserved Top Level DNS Names»).

Сторона, создающая SWT, является производителем SWT. Сторона, проверяющая SWT, является потребителем SWT. Перед созданием SWT производитель и потребителем согласились с использованием атрибутов, содержащихся в SWT, и обменялись внешним произвольно сгенерированным 256-разрядным ключом. Чтобы создать SWT, производитель выполняет следующие действия.

  1. Собирает пары «имя-значение» для передачи в SWT и кодирует их как application/x-www-form-urlencoded согласно 17.13.4 для HTML 4.01

  2. Вводит закодированный SWT и согласованный ключ в процесс SHA 256 HMAC.

  3. Получает результирующее значение HMAC и кодирует его с помощью Base64 согласно разделу 4 в RFC 4648.

  4. Следует правилам кодирования форм, добавляет имя «HMACSHA256» и значение HMAC в кодировке base-64 в конец закодированного SWT.

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

  1. Принимает отправленный SWT и разделяет строку на часть до «&HMACSHA256=» и оставшуюся часть, которая является URL-адресом, закодированным с помощью алгоритма HMAC. Первая часть — noHMACSWT.

  2. Декодирует URL-адрес остальной части строки SWT. Это submittedHMAC.

  3. Создает HMAC для noHMACSWT с помощью согласованного ключа и затем кодирует с помощью Base64 согласно разделу 4 в RFC 4648. Итоговая строка — localHMAC.

  4. Выполняет посимвольное сравнение submittedHMAC и localHMAC. Если строки равны, HMAC в SWT является допустимым.

Производитель SWT хочет выдавать SWT со следующими сведениями:

Issuer = issuer.example.com
ExpiresOn = 1/1/2010, Midnight
com.example.group = gold
over18 = true

со значением ключа HMAC (представленным в base 64), равным:

N4QeKa3c062VBjnVK6fb+rnwURkcwGXh7EoNK34n0uM=

В этом примере Issuer и ExpiresOn являются зарезервированными именами из данной спецификации. Атрибут com.example.group согласован в определении синтаксиса и семантики группы, созданной владельцем домена example.com. over18 — это отдельно определенный атрибут, согласованный между производителем и потребителем SWT.

Прежде чем закодировать SWT, нужно преобразовать ExpiresOn в значение, равное количеству секунд с 01.01.1970, полночь (UTC) до времени истечения срока действия — 01.01.2010, полночь. Результат — 1 262 304 000.

  1. Закодируйте пары «имя-значение» в HTML-форму. Результат (разрывы строк вставлены для удобства чтения):

    Issuer=issuer.example.com&
    ExpiresOn=1262304000&
    com.example.group=gold&
    over18=true
    
  2. Далее следует рассчитать HMAC предыдущего значения с помощью ключа.

  3. Выполните кодирование HMAC в формате Base64. Результат:

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=
    
  4. Выполните URL-кодирование итогового HMAC в кодировке base64 и прикрепите его к концу утверждения. Результирующий SWT (разрывы строк вставлены для удобства чтения):

    Issuer=issuer.example.com&
    ExpiresOn=1262304000&
    com.example.group=gold&
    over18=true&
    HMACSHA256=
    AT55%2B2jLQeuigpg0xm%2Fvn7tjpSGXBUfFe0UXb0%2F9opE%3D
    

  1. Разделите SWT с помощью: &HMACSHA256= Будет получена строка noHMACSWT (переводы строк добавлены для удобства чтения):

    Issuer=issuer.example.com&
    ExpiresOn=1262304000&
    com.example.group=gold&
    over18=true&
    
    и строка submittedHMAC:

    AT55%2B2jLQeuigpg0xm%2Fvn7tjpSGXBUfFe0UXb0%2F9opE%3D
    
  2. Далее выполните URL-декодирование submittedHMAC. Будет получен следующий результат:

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=
    
  3. Затем следует вычислить localHMAC с помощью noHMACSWT и значения ключа HMAC, закодировать результат в формате base64. Будет получено следующее значение localHMAC:

    AT55+2jLQeuigpg0xm/vn7tjpSGXBUfFe0UXb0/9opE=
    
  4. Итогом сравнения submittedHMAC и localHMAC будет одна и та же строка. Затем для получения доступа к значениям SWT выполняется URL-декодирование noHMACSWT.

Следующие пары «имя-значение» являются необязательными. Они определены для упрощения взаимодействия в рамках некоторых распространенных сценариев.

 

Название Синтаксис значения Семантика значения

Issuer

Строка в кодировке UTF-8

Определяет сторону, которая выдает SWT.

ExpiresOn

Строка ASCII, представляющая целое число (с основанием 10) без знака.

Определяет момент, когда SWT не следует принимать для дальнейшей обработки.

Дата и время окончания действия записываются в виде количества секунд, которое пройдет с 01.01.1970T0:0:0Z до момента истечения срока действия в формате UTC.

Аудитория

Строка в кодировке UTF-8

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

Для определения дополнительных атрибутов производитель SWT может использовать обратное DNS-имя или URI.

Производитель и потребитель SWT могут согласовать и принять любое имя атрибута, которое не является зарезервированным или общедоступным. Эти имена не должны входить в список зарезервированных имен, определенных в предыдущем разделе «Зарезервированные имена». В отличие от общедоступных имен, закрытые имена могут стать причиной возникновения конфликтов, поэтому их следует использовать с осторожностью.

См. также

Показ: