О документе
Internet Engineering Task Force (IETF) M. Jones
Запрос комментариев: 7519 Microsoft
Категория: На пути к стандарту J. Bradley
ISSN: 2070-1721 Ping Identity
N. Sakimura
NRI
Май 2015
JSON Web Token (JWT)
1. Введение
JSON Web Token (JWT) — это компактный формат представления
утверждений, предназначенный для сред с ограниченным объёмом
доступного места, таких как заголовки HTTP Authorization и параметры
запроса URI. JWT кодируют передаваемые утверждения как объект JSON
[RFC7159], который используется в качестве полезной нагрузки
структуры JSON Web Signature (JWS) [JWS] или открытого текста
структуры JSON Web Encryption (JWE) [JWE], что позволяет подписывать
утверждения цифровой подписью или защищать их целостность с помощью
кода аутентификации сообщения (Message Authentication Code, MAC)
и/или шифровать их. JWT всегда представляются с использованием
компактной сериализации JWS (JWS Compact Serialization) или
компактной сериализации JWE (JWE Compact Serialization).
JWT предлагается произносить так же, как английское слово "jot".
1.1. Условные обозначения
Ключевые слова «ДОЛЖЕН (MUST)», «НЕ ДОЛЖЕН (MUST NOT)»,
«ДОЛЖЕН (REQUIRED)», «ДОЛЖЕН (SHALL)», «НЕ ДОЛЖЕН (SHALL NOT)»,
«СЛЕДУЕТ (SHOULD)», «НЕ СЛЕДУЕТ (SHOULD NOT)»,
«СЛЕДУЕТ (RECOMMENDED)», «НЕ СЛЕДУЕТ (NOT RECOMMENDED)»,
«МОЖЕТ (MAY)» и «НЕОБЯЗАТЕЛЬНО (OPTIONAL)» в этом документе
интерпретируются в соответствии с "Key words for use in RFCs to
Indicate Requirement Levels" [RFC2119]. Эту интерпретацию следует
применять только тогда, когда термины написаны целиком прописными
буквами.
2. Терминология
Термины «JSON Web Signature (JWS)», «кодирование Base64url
(Base64url Encoding)», «параметр заголовка (Header Parameter)»,
«заголовок JOSE (JOSE Header)», «компактная сериализация JWS
(JWS Compact Serialization)», «полезная нагрузка JWS (JWS Payload)»,
«подпись JWS (JWS Signature)» и «незащищённый JWS (Unsecured JWS)»
определены в спецификации JWS [JWS].
Термины «JSON Web Encryption (JWE)», «ключ шифрования содержимого
(Content Encryption Key, CEK)», «компактная сериализация JWE
(JWE Compact Serialization)», «зашифрованный ключ JWE (JWE Encrypted
Key)» и «вектор инициализации JWE (JWE Initialization Vector)»
определены в спецификации JWE [JWE].
Термины «шифротекст (Ciphertext)», «цифровая подпись (Digital
Signature)», «код аутентификации сообщения (Message Authentication
Code, MAC)» и «открытый текст (Plaintext)» определены в "Internet
Security Glossary, Version 2" [RFC4949].
Следующие термины определены в этой спецификации:
JSON Web Token (JWT)
Строка, представляющая набор утверждений в виде объекта JSON,
закодированного в JWS или JWE, что позволяет подписывать
утверждения цифровой подписью или защищать их с помощью MAC
и/или шифровать их.
Набор утверждений JWT (JWT Claims Set)
Объект JSON, содержащий утверждения, передаваемые JWT.
Утверждение (Claim)
Сведение, утверждаемое о некотором субъекте. Утверждение
представляется парой «имя/значение», состоящей из имени
утверждения и значения утверждения.
Имя утверждения (Claim Name)
Часть представления утверждения, содержащая имя. Имя утверждения
всегда является строкой.
Значение утверждения (Claim Value)
Часть представления утверждения, содержащая значение. Значение
утверждения может быть любым значением JSON.
Вложенный JWT (Nested JWT)
JWT, в котором применяются вложенные операции подписания и/или
шифрования. Во вложенных JWT один JWT используется в качестве
полезной нагрузки или открытого текста охватывающей его
структуры JWS или JWE соответственно.
Незащищённый JWT (Unsecured JWT)
JWT, утверждения которого не защищены от нарушения целостности
и не зашифрованы.
Имя, устойчивое к коллизиям (Collision-Resistant Name)
Имя в пространстве имён, позволяющем выделять имена таким образом,
что вероятность их совпадения с другими именами крайне мала.
Примеры пространств имён, устойчивых к коллизиям: доменные имена,
идентификаторы объектов (Object Identifiers, OID), определённые
в сериях рекомендаций ITU-T X.660 и X.670, и универсальные
уникальные идентификаторы (Universally Unique IDentifiers, UUID)
[RFC4122]. При использовании административно делегированного
пространства имён лицо, определяющее имя, должно принять разумные
меры предосторожности, чтобы убедиться, что используемая для
определения имени часть пространства имён находится под его
контролем.
StringOrURI
Строковое значение JSON с дополнительным требованием: хотя
произвольные строковые значения МОГУТ (MAY) использоваться,
любое значение, содержащее символ ":", ДОЛЖНО (MUST) быть URI
[RFC3986]. Значения StringOrURI сравниваются как строки с учётом
регистра без применения каких-либо преобразований или
канонизации.
NumericDate
Числовое значение JSON, представляющее количество секунд от
1970-01-01T00:00:00Z UTC до указанной даты и времени UTC без учёта
дополнительных секунд координации. Это эквивалентно определению
"Seconds Since the Epoch" в IEEE Std 1003.1, 2013 Edition
[POSIX.1], в котором каждые сутки учитываются как ровно 86400
секунд, с тем отличием, что здесь могут быть представлены
нецелые значения. Подробности о датах и времени в целом и UTC
в частности см. в RFC 3339 [RFC3339].
3. Обзор JSON Web Token (JWT)
JWT представляют набор утверждений в виде объекта JSON,
закодированного в структуре JWS и/или JWE. Этот объект JSON является
набором утверждений JWT. Согласно разделу 4 RFC 7159 [RFC7159],
объект JSON состоит из нуля или более пар «имя/значение» (или членов),
где имена являются строками, а значения — произвольными значениями
JSON. Эти члены являются утверждениями, представленными JWT. Этот
объект JSON МОЖЕТ (MAY) содержать пробельные символы и/или переводы
строк до или после любых значений JSON или структурных символов
в соответствии с разделом 2 RFC 7159 [RFC7159].
Имена членов в наборе утверждений JWT называются именами утверждений.
Соответствующие значения называются значениями утверждений.
Содержимое заголовка JOSE описывает криптографические операции,
применяемые к набору утверждений JWT. Если заголовок JOSE относится
к JWS, JWT представляется как JWS, а утверждения подписываются
цифровой подписью или защищаются с помощью MAC; при этом набор
утверждений JWT является полезной нагрузкой JWS. Если заголовок
JOSE относится к JWE, JWT представляется как JWE, а утверждения
шифруются; при этом набор утверждений JWT является открытым текстом,
шифруемым JWE. JWT может быть заключён в другую структуру JWE или
JWS для создания вложенного JWT, что позволяет выполнять вложенные
операции подписания и шифрования.
JWT представляется в виде последовательности безопасных для
использования в URL частей, разделённых символами точки ('.').
Каждая часть содержит значение, закодированное с помощью base64url.
Количество частей в JWT зависит от представления результирующего
JWS с использованием компактной сериализации JWS или JWE
с использованием компактной сериализации JWE.
3.1. Пример JWT
Следующий пример заголовка JOSE объявляет, что закодированный объект
является JWT, а этот JWT является JWS, защищённым с помощью MAC
с использованием алгоритма HMAC SHA-256:
{"typ":"JWT",
"alg":"HS256"}
Чтобы устранить возможные неоднозначности в представлении приведённого выше объекта JSON, ниже также приведена последовательность октетов фактического представления UTF-8, использованного в этом примере для приведённого выше заголовка JOSE. (Обратите внимание, что неоднозначности могут возникать из-за различий в представлении разрывов строк на разных платформах (CRLF или LF), различий в пробелах в начале и конце строк, наличия или отсутствия завершающего разрыва строки в последней строке и по другим причинам. В представлении, используемом в этом примере, первая строка не имеет начальных или конечных пробелов, между первой и второй строками находится разрыв строки CRLF (13, 10), вторая строка имеет один начальный пробел (32) и не имеет конечных пробелов, а последняя строка не имеет завершающего разрыва строки.) Октеты представления UTF-8 заголовка JOSE в этом примере (в записи массива JSON):
[123, 34, 116, 121, 112, 34, 58, 34, 74, 87, 84, 34, 44, 13, 10, 32,
34, 97, 108, 103, 34, 58, 34, 72, 83, 50, 53, 54, 34, 125]
Кодирование октетов представления UTF-8 заголовка JOSE с помощью base64url даёт следующее закодированное значение заголовка JOSE:
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
Ниже приведён пример набора утверждений JWT:
{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}
Следующая последовательность октетов, представляющая использованное в этом примере представление UTF-8 приведённого выше набора утверждений JWT, является полезной нагрузкой JWS:
[123, 34, 105, 115, 115, 34, 58, 34, 106, 111, 101, 34, 44, 13, 10,
32, 34, 101, 120, 112, 34, 58, 49, 51, 48, 48, 56, 49, 57, 51, 56,
48, 44, 13, 10, 32, 34, 104, 116, 116, 112, 58, 47, 47, 101, 120, 97,
109, 112, 108, 101, 46, 99, 111, 109, 47, 105, 115, 95, 114, 111,
111, 116, 34, 58, 116, 114, 117, 101, 125]
Кодирование полезной нагрузки JWS с помощью base64url даёт следующую закодированную полезную нагрузку JWS (разрывы строк добавлены только для отображения):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly
9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Вычисление MAC закодированного заголовка JOSE и закодированной полезной нагрузки JWS с помощью алгоритма HMAC SHA-256 и кодирование значения HMAC с помощью base64url способом, указанным в [JWS], даёт следующую закодированную подпись JWS:
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Соединение этих закодированных частей в указанном порядке с символами точки ('.') между частями даёт следующий полный JWT (разрывы строк добавлены только для отображения):
eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Это вычисление подробнее проиллюстрировано в приложении A.1 документа [JWS]. Пример зашифрованного JWT приведён в приложении A.1.
4. Утверждения JWT
Набор утверждений JWT представляет собой объект JSON, члены которого являются утверждениями, передаваемыми в JWT. Имена утверждений в наборе утверждений JWT ДОЛЖНЫ (MUST) быть уникальными; средства разбора JWT ДОЛЖНЫ (MUST) либо отклонять JWT с повторяющимися именами утверждений, либо использовать средство разбора JSON, которое возвращает только лексически последнее из повторяющихся имён членов, как указано в разделе 15.12 ("The JSON Object") ECMAScript 5.1 [ECMAScript].
Набор утверждений, которые JWT должен содержать, чтобы считаться действительным, зависит от контекста и выходит за рамки этой спецификации. Конкретные применения JWT будут требовать, чтобы реализации понимали и обрабатывали некоторые утверждения определёнными способами. Однако при отсутствии таких требований все утверждения, которые реализации не понимают, ДОЛЖНЫ (MUST) игнорироваться.
Существуют три класса имён утверждений JWT: зарегистрированные имена утверждений, публичные имена утверждений и частные имена утверждений.
4.1. Зарегистрированные имена утверждений
Следующие имена утверждений зарегистрированы в реестре IANA "JSON Web Token Claims", учреждённом разделом 10.1. Ни одно из определённых ниже утверждений не предназначено для обязательного использования или реализации во всех случаях; они служат отправной точкой для набора полезных утверждений, обеспечивающих совместимость. Приложениям, использующим JWT, следует определять, какие именно утверждения они используют и когда эти утверждения обязательны или необязательны. Все имена короткие, поскольку одна из основных целей JWT — компактность представления.
4.1.1. Утверждение "iss" (издатель)
Утверждение "iss" (издатель) идентифицирует субъекта, выпустившего JWT. Обработка этого утверждения обычно зависит от приложения. Значение "iss" — строка с учётом регистра, содержащая значение StringOrURI. Использование этого утверждения НЕОБЯЗАТЕЛЬНО (OPTIONAL).
4.1.2. Утверждение "sub" (субъект)
Утверждение "sub" (субъект) идентифицирует субъекта, о котором идёт речь в JWT. Утверждения в JWT обычно представляют собой высказывания об этом субъекте. Значение субъекта ДОЛЖНО (MUST) либо быть локально уникальным в контексте издателя, либо быть глобально уникальным. Обработка этого утверждения обычно зависит от приложения. Значение "sub" — строка с учётом регистра, содержащая значение StringOrURI. Использование этого утверждения НЕОБЯЗАТЕЛЬНО (OPTIONAL).
4.1.3. Утверждение "aud" (аудитория)
Утверждение "aud" (аудитория) идентифицирует получателей, которым предназначен JWT. Каждый субъект, которому предназначено обрабатывать JWT, ДОЛЖЕН (MUST) идентифицировать себя по значению в утверждении аудитории. Если субъект, обрабатывающий утверждение, не идентифицирует себя по значению в утверждении "aud", когда это утверждение присутствует, то JWT ДОЛЖЕН (MUST) быть отклонён. В общем случае значение "aud" представляет собой массив строк с учётом регистра, каждая из которых содержит значение StringOrURI. В частном случае, когда JWT имеет одну аудиторию, значение "aud" МОЖЕТ (MAY) быть одной строкой с учётом регистра, содержащей значение StringOrURI. Интерпретация значений аудитории обычно зависит от приложения. Использование этого утверждения НЕОБЯЗАТЕЛЬНО (OPTIONAL).
4.1.4. Утверждение "exp" (время истечения срока действия)
Утверждение "exp" (время истечения срока действия) указывает время истечения срока действия, при наступлении которого и после которого JWT НЕ ДОЛЖЕН (MUST NOT) приниматься для обработки. Обработка утверждения "exp" требует, чтобы текущие дата и время ДОЛЖНЫ (MUST) были предшествовать дате и времени истечения срока действия, указанным в утверждении "exp".
Разработчики реализаций МОГУТ (MAY) предусмотреть небольшой допуск, обычно не более нескольких минут, для учёта расхождения часов. Значение этого утверждения ДОЛЖНО (MUST) быть числом, содержащим значение NumericDate. Использование этого утверждения НЕОБЯЗАТЕЛЬНО (OPTIONAL).
4.1.5. Утверждение "nbf" (не ранее)
Утверждение "nbf" (не ранее) указывает время, до которого JWT НЕ ДОЛЖЕН (MUST NOT) приниматься для обработки. При обработке утверждения "nbf" текущие дата и время ДОЛЖНЫ (MUST) быть не ранее даты и времени, указанных в утверждении "nbf". Разработчики реализаций МОГУТ (MAY) предусмотреть небольшой допуск, обычно не более нескольких минут, для учёта расхождения часов. Значение этого утверждения ДОЛЖНО (MUST) быть числом, содержащим значение NumericDate. Использование этого утверждения НЕОБЯЗАТЕЛЬНО (OPTIONAL).
4.1.6. Утверждение "iat" (время выпуска)
Утверждение "iat" (время выпуска) указывает время, когда был выпущен JWT. Это утверждение может использоваться для определения возраста JWT. Значение этого утверждения ДОЛЖНО (MUST) быть числом, содержащим значение NumericDate. Использование этого утверждения НЕОБЯЗАТЕЛЬНО (OPTIONAL).
4.1.7. Утверждение "jti" (идентификатор JWT)
Утверждение "jti" (идентификатор JWT) предоставляет уникальный идентификатор JWT. Значение идентификатора ДОЛЖНО (MUST) назначаться таким образом, чтобы вероятность случайного назначения того же значения другому объекту данных была пренебрежимо малой; если приложение использует нескольких издателей, коллизии между значениями, создаваемыми разными издателями, также ДОЛЖНЫ (MUST) предотвращаться. Утверждение "jti" может использоваться для предотвращения повторного использования JWT. Значение "jti" — строка с учётом регистра. Использование этого утверждения НЕОБЯЗАТЕЛЬНО (OPTIONAL).
4.2. Публичные имена утверждений
Пользователи JWT могут определять имена утверждений по своему усмотрению. Однако для предотвращения коллизий любое новое имя утверждения следует либо зарегистрировать в реестре IANA "JSON Web Token Claims", учреждённом разделом 10.1, либо сделать публичным именем: значением, содержащим имя, устойчивое к коллизиям. В каждом случае тому, кто определяет имя или значение, необходимо принять разумные меры предосторожности, чтобы убедиться, что используемая им для определения имени утверждения часть пространства имён находится под его контролем.
4.3. Частные имена утверждений
Создатель и потребитель JWT МОГУТ (MAY) договориться об использовании имён утверждений, являющихся частными именами: имён, которые не являются зарегистрированными именами утверждений (раздел 4.1) или публичными именами утверждений (раздел 4.2). В отличие от публичных
имён утверждений, частные имена утверждений подвержены коллизиям, и их следует использовать с осторожностью.
5. Заголовок JOSE
Для объекта JWT члены объекта JSON, представленного заголовком JOSE, описывают криптографические операции, применённые к JWT, и, при необходимости, дополнительные свойства JWT. В зависимости от того, является ли JWT объектом JWS или JWE, применяются соответствующие правила для значений заголовка JOSE.
Эта спецификация дополнительно определяет использование следующих параметров заголовка как в случае, когда JWT является JWS, так и в случае, когда он является JWE.
5.1. Параметр заголовка "typ" (тип)
Параметр заголовка "typ" (тип), определённый в [JWS] и [JWE], используется приложениями JWT для объявления типа данных [IANA.MediaTypes] этого полного JWT. Он предназначен для использования приложением JWT в тех случаях, когда в структуре данных приложения, которая может содержать объект JWT, могут также присутствовать значения, не являющиеся JWT; приложение может использовать это значение для различения разных видов объектов, которые могут присутствовать. Обычно приложения не используют его, когда уже известно, что объект является JWT. Этот параметр игнорируется реализациями JWT; любая обработка этого параметра выполняется приложением JWT. Если он присутствует, его значением СЛЕДУЕТ (RECOMMENDED) указывать "JWT", чтобы обозначить, что этот объект является JWT. Хотя имена типов данных не зависят от регистра, "JWT" СЛЕДУЕТ (RECOMMENDED) всегда записывать прописными буквами для совместимости с унаследованными реализациями. Использование этого параметра заголовка НЕОБЯЗАТЕЛЬНО (OPTIONAL).
5.2. Параметр заголовка "cty" (тип содержимого)
Параметр заголовка "cty" (тип содержимого), определённый в [JWS] и [JWE], используется в этой спецификации для передачи структурной информации о JWT.
В обычном случае, когда вложенные операции подписания или шифрования не применяются, использовать этот параметр заголовка НЕ СЛЕДУЕТ (NOT RECOMMENDED). В случае применения вложенного подписания или шифрования этот параметр заголовка ДОЛЖЕН (MUST) присутствовать; в этом случае его значение ДОЛЖНО (MUST) быть "JWT", чтобы указать, что в этом JWT передаётся вложенный JWT. Хотя имена типов данных не зависят от регистра, "JWT" СЛЕДУЕТ (RECOMMENDED) всегда записывать прописными буквами для совместимости с унаследованными реализациями. Пример вложенного JWT приведён в приложении A.2.
5.3. Дублирование утверждений в параметрах заголовка
В некоторых приложениях, использующих зашифрованные JWT, полезно иметь незашифрованное представление некоторых утверждений. Например, оно может использоваться в правилах обработки приложения для определения того, следует ли обрабатывать JWT и каким образом, прежде чем он будет расшифрован.
Эта спецификация разрешает дублировать утверждения, присутствующие в наборе утверждений JWT, в виде параметров заголовка в JWT, являющемся JWE, по мере необходимости для приложения. Если такие дублированные утверждения присутствуют, принимающему их приложению СЛЕДУЕТ (SHOULD) проверить, что их значения идентичны, если только приложение не определяет иные конкретные правила обработки этих утверждений. Приложение несёт ответственность за обеспечение того, чтобы в качестве значений параметров заголовка в JWT дублировались только утверждения, которые безопасно передавать в незашифрованном виде.
Раздел 10.4.1 этой спецификации регистрирует имена параметров заголовка "iss" (издатель), "sub" (субъект) и "aud" (аудитория) для предоставления незашифрованных копий этих утверждений в зашифрованных JWT приложениям, которым они необходимы. Другие спецификации аналогичным образом МОГУТ (MAY) по мере необходимости регистрировать другие имена, являющиеся зарегистрированными именами утверждений, в качестве имён параметров заголовка.
6. Незащищённые JWT
Для поддержки сценариев использования, в которых содержимое JWT защищается средствами, отличными от подписи и/или шифрования, содержащихся в самом JWT (например, подписью структуры данных, содержащей JWT), JWT также МОГУТ (MAY) создаваться без подписи или шифрования. Незащищённый JWT — это JWS со значением "none" параметра заголовка "alg" и пустой строкой в качестве значения подписи JWS, как определено в спецификации JWA [JWA]; это незащищённый JWS, полезной нагрузкой JWS которого является набор утверждений JWT.
6.1. Пример незащищённого JWT
Следующий пример заголовка JOSE объявляет, что закодированный объект является незащищённым JWT:
{"alg":"none"}
Кодирование октетов представления UTF-8 заголовка JOSE с помощью base64url даёт следующее закодированное значение заголовка JOSE:
eyJhbGciOiJub25lIn0
Ниже приведён пример набора утверждений JWT:
{"iss":"joe",
"exp":1300819380,
"http://example.com/is_root":true}
Кодирование base64url октетов представления набора утверждений JWT в UTF-8 даёт следующую закодированную полезную нагрузку JWS (переносы строк добавлены только для отображения):
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
Закодированная подпись JWS представляет собой пустую строку.
Соединение этих закодированных частей в указанном порядке с символами точки ('.') между частями даёт следующий полный JWT (переносы строк добавлены только для отображения):
eyJhbGciOiJub25lIn0
.
eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt
cGxlLmNvbS9pc19yb290Ijp0cnVlfQ
.
7. Создание и проверка JWT
7.1. Создание JWT
Для создания JWT выполняются следующие шаги. Порядок шагов не имеет значения в тех случаях, когда между входными и выходными данными шагов нет зависимостей.
1. Создать набор утверждений JWT, содержащий нужные утверждения. Обратите внимание, что пробельные символы явно разрешены в представлении и перед кодированием не требуется выполнять канонизацию.
2. Принять за Сообщение октеты представления набора утверждений JWT в UTF-8.
3. Создать заголовок JOSE, содержащий нужный набор параметров заголовка. JWT ДОЛЖЕН (MUST) соответствовать спецификации [JWS] или [JWE]. Обратите внимание, что пробельные символы явно разрешены в представлении и перед кодированием не требуется выполнять канонизацию.
4. В зависимости от того, является JWT структурой JWS или JWE, возможны два случая:
* Если JWT является структурой JWS, создать JWS, используя Сообщение в качестве полезной нагрузки JWS; все шаги, указанные в [JWS] для создания JWS, ДОЛЖНЫ (MUST) быть выполнены.
* В противном случае, если JWT является структурой JWE, создать JWE, используя Сообщение в качестве открытого текста для JWE; все шаги, указанные в [JWE] для создания JWE, ДОЛЖНЫ (MUST) быть выполнены.
5. Если будет выполняться вложенная операция подписания или шифрования, принять за Сообщение структуру JWS или JWE и вернуться к шагу 3, используя значение "JWT" для "cty" (тип содержимого) в новом заголовке JOSE, создаваемом на этом шаге.
6. В противном случае принять структуру JWS или JWE за результирующий JWT.
7.2. Проверка JWT
При проверке JWT выполняются следующие шаги. Порядок шагов не имеет значения в тех случаях, когда между входными и выходными данными шагов нет зависимостей. Если какой-либо из перечисленных шагов завершается неудачей, JWT ДОЛЖЕН (MUST) быть отклонён, то есть обработан приложением как недопустимые входные данные.
1. Убедиться, что JWT содержит хотя бы один символ точки ('.').
2. Принять за Закодированный заголовок JOSE часть JWT, предшествующую первому символу точки ('.').
3. Декодировать Закодированный заголовок JOSE из base64url, соблюдая ограничение, согласно которому в нём не должны использоваться переносы строк, пробельные или какие-либо иные дополнительные символы.
4. Убедиться, что полученная последовательность октетов представляет собой закодированное в UTF-8 представление полностью корректного объекта JSON, соответствующего RFC 7159 [RFC7159]; принять этот объект JSON за заголовок JOSE.
5. Убедиться, что полученный заголовок JOSE включает только такие параметры и значения, синтаксис и семантика которых понятны и поддерживаются либо для которых предписано игнорирование, если они непонятны.
6. Определить, является JWT структурой JWS или JWE, используя любой из методов, описанных в разделе 9 [JWE].
7. В зависимости от того, является JWT структурой JWS или JWE, возможны два случая:
* Если JWT является структурой JWS, выполнить шаги, указанные в [JWS] для проверки JWS. Принять за Сообщение результат декодирования полезной нагрузки JWS из base64url.
* В противном случае, если JWT является структурой JWE, выполнить шаги, указанные в [JWE] для проверки JWE. Принять за Сообщение полученный открытый текст.
8. Если заголовок JOSE содержит значение "JWT" для "cty" (тип содержимого), то Сообщение является JWT, над которым выполнялись вложенные операции подписания или шифрования. В этом случае вернуться к шагу 1, используя Сообщение в качестве JWT.
9. В противном случае декодировать Сообщение из base64url, соблюдая ограничение, согласно которому в нём не должны использоваться переносы строк, пробельные или какие-либо иные дополнительные символы.
10. Убедиться, что полученная последовательность октетов представляет собой закодированное в UTF-8 представление полностью корректного объекта JSON, соответствующего RFC 7159 [RFC7159]; принять этот объект JSON за набор утверждений JWT.
Наконец, обратите внимание, что решение о том, какие алгоритмы могут использоваться в данном контексте, принимает приложение. Даже если JWT может успешно пройти проверку, приложению СЛЕДУЕТ (SHOULD) отклонить JWT, если использованные в нём алгоритмы неприемлемы для приложения.
7.3. Правила сравнения строк
Обработка JWT неизбежно требует сравнения известных строк с членами объектов JSON и их значениями. Например, при определении алгоритма строка Unicode [UNICODE], кодирующая "alg", будет сравниваться с именами членов заголовка JOSE, чтобы выяснить, имеется ли совпадающее имя параметра заголовка.
Правила JSON для сравнения имён членов описаны в разделе 8.3 RFC 7159 [RFC7159]. Поскольку единственными выполняемыми операциями сравнения строк являются проверки на равенство и неравенство, одни и те же правила можно использовать для сравнения с известными строками как имён членов, так и их значений.
Эти правила сравнения ДОЛЖНЫ (MUST) использоваться для всех сравнений строк JSON, кроме случаев, когда в определении члена явно указано, что для значения этого члена должно использоваться другое правило сравнения. В данной спецификации эти правила сравнения не используются только для значений членов "typ" и "cty".
Некоторые приложения могут включать информацию, не зависящую от регистра, в значение, чувствительное к регистру, например включать имя DNS как часть значения утверждения "iss" (издатель). В таких случаях приложению может потребоваться определить соглашение о каноническом регистре, используемом для представления частей, не зависящих от регистра, например о приведении их к нижнему регистру, если нескольким сторонам может потребоваться сформировать одно и то же значение для последующего сравнения. (Однако если все остальные стороны используют любое значение, выданное формирующей стороной, без изменений и без попыток сравнить его с независимо сформированным значением, регистр, использованный формирующей стороной, не будет иметь значения.)
8. Требования к реализации
В этом разделе определяется, какие алгоритмы и возможности данной спецификации обязательны для реализации. Приложения, использующие эту спецификацию, могут предъявлять дополнительные требования к используемым ими реализациям. Например, одно приложение может требовать поддержки зашифрованных JWT и вложенных JWT, тогда как другое может требовать поддержки подписания JWT с помощью Elliptic Curve Digital Signature Algorithm (ECDSA) с использованием кривой P-256 и алгоритма хеширования SHA-256 ("ES256").
Из алгоритмов подписи и MAC, указанных в JSON Web Algorithms [JWA], обязательными для реализации являются только HMAC SHA-256 ("HS256") и "none"; соответствующие данной спецификации реализации JWT ДОЛЖНЫ (MUST) их реализовывать. Реализациям также СЛЕДУЕТ (RECOMMENDED) поддерживать RSASSA-PKCS1-v1_5 с алгоритмом хеширования SHA-256 ("RS256") и ECDSA с использованием кривой P-256 и алгоритма хеширования SHA-256 ("ES256"). Поддержка других алгоритмов и размеров ключей НЕОБЯЗАТЕЛЬНА (OPTIONAL).
Поддержка зашифрованных JWT НЕОБЯЗАТЕЛЬНА (OPTIONAL). Если реализация предоставляет возможности шифрования, то из алгоритмов шифрования, указанных в [JWA], обязательными для реализации являются только RSAES-PKCS1-v1_5 с 2048-битными ключами ("RSA1_5"), AES Key Wrap со 128- и 256-битными ключами ("A128KW" и "A256KW") и составной алгоритм аутентифицированного шифрования с использованием AES-CBC и HMAC SHA-2 ("A128CBC-HS256" и "A256CBC-HS512"); соответствующие данной спецификации реализации с возможностями шифрования ДОЛЖНЫ (MUST) их реализовывать. Реализациям также СЛЕДУЕТ (RECOMMENDED) поддерживать использование Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES) для согласования ключа, используемого для обёртывания ключа шифрования содержимого ("ECDH-ES+A128KW" и "ECDH-ES+A256KW"), и AES в режиме Galois/Counter Mode (GCM) со 128- и 256-битными ключами ("A128GCM" и "A256GCM"). Поддержка других алгоритмов и размеров ключей НЕОБЯЗАТЕЛЬНА (OPTIONAL).
Поддержка вложенных JWT НЕОБЯЗАТЕЛЬНА (OPTIONAL).
9. URI для объявления содержимого как JWT
Данная спецификация регистрирует URN "urn:ietf:params:oauth:token-type:jwt" для использования приложениями, которые объявляют типы содержимого с помощью URI (а не, например, типов медиа), чтобы указывать, что содержимое, на которое ссылаются, является JWT.
10.1. Реестр JSON Web Token Claims
В этом разделе учреждается реестр IANA "JSON Web Token Claims" для имён утверждений JWT. В реестре записываются имя утверждения и ссылка на спецификацию, которая его определяет. В этом разделе регистрируются имена утверждений, определённые в разделе 4.1.
Значения регистрируются в соответствии с политикой Specification Required [RFC5226] после трёхнедельного периода рассмотрения в списке рассылки jwt-reg-review@ietf.org по рекомендации одного или нескольких назначенных экспертов. Однако, чтобы обеспечить возможность выделения значений до публикации, назначенные эксперты могут одобрить регистрацию, как только убедятся, что такая спецификация будет опубликована.
Запросы на регистрацию, отправляемые в список рассылки для рассмотрения, следует снабжать подходящей темой (например, "Request to register claim: example").
В течение периода рассмотрения назначенные эксперты либо одобрят, либо отклонят запрос на регистрацию, сообщив это решение в список рассылки для рассмотрения и в IANA. Отказы следует сопровождать объяснением и, если применимо, предложениями о том, как добиться одобрения запроса. Запросы на регистрацию, по которым решение не принято в течение более чем 21 дня, можно передать на рассмотрение IESG (через список рассылки iesg@ietf.org) для разрешения вопроса.
Критерии, которые следует применять назначенным экспертам, включают определение того, дублирует ли предлагаемая регистрация существующие функциональные возможности, будет ли она, вероятно, иметь общее применение или полезна лишь для одного приложения, а также ясно ли изложено описание регистрации.
IANA должна принимать обновления реестра только от назначенных экспертов; ей следует направлять все запросы на регистрацию в список рассылки для рассмотрения.
Предлагается назначать нескольких назначенных экспертов, способных представлять точки зрения разных приложений, использующих данную спецификацию, чтобы обеспечить всесторонне информированное рассмотрение регистрационных решений. В случаях, когда решение о регистрации может
восприниматься как создающее конфликт интересов для конкретного эксперта, этому эксперту следует положиться на суждение других экспертов.
10.1.1. Шаблон регистрации
Claim Name:
Запрашиваемое имя (например, "iss"). Поскольку одна из основных целей данной спецификации — компактность получаемых представлений, СЛЕДУЕТ (RECOMMENDED) выбирать короткое имя, то есть не превышающее 8 символов без веской причины. Это имя чувствительно к регистру. Имена не могут совпадать с другими зарегистрированными именами при сравнении без учёта регистра, если только назначенные эксперты не укажут, что имеется веская причина разрешить исключение.
Claim Description:
Краткое описание утверждения (например, "Issuer").
Change Controller:
Для RFC категории Standards Track указать "IESG". Для остальных указать имя ответственной стороны. Также могут быть включены другие сведения (например, почтовый адрес, адрес электронной почты, URI домашней страницы).
Specification Document(s):
Ссылка на документ или документы, определяющие параметр, желательно с URI, которые можно использовать для получения копий документов. Также можно указать соответствующие разделы, но это не требуется.
10.1.2. Первоначальное содержимое реестра
o Claim Name: "iss"
o Claim Description: Issuer
o Change Controller: IESG
o Specification Document(s): Section 4.1.1 of RFC 7519
o Claim Name: "sub"
o Claim Description: Subject
o Change Controller: IESG
o Specification Document(s): Section 4.1.2 of RFC 7519
o Claim Name: "aud"
o Claim Description: Audience
o Change Controller: IESG
o Specification Document(s): Section 4.1.3 of RFC 7519
o Claim Name: "exp"
o Claim Description: Expiration Time
o Change Controller: IESG
o Specification Document(s): Section 4.1.4 of RFC 7519
o Claim Name: "nbf"
o Claim Description: Not Before
o Change Controller: IESG
o Specification Document(s): Section 4.1.5 of RFC 7519
o Claim Name: "iat"
o Claim Description: Issued At
o Change Controller: IESG
o Specification Document(s): Section 4.1.6 of RFC 7519
o Имя утверждения: "jti"
o Описание утверждения: идентификатор JWT
o Ответственный за изменения: IESG
o Документ(ы) спецификации: раздел 4.1.7 RFC 7519
10.2. Регистрация подпространства имён
urn:ietf:params:oauth:token-type:jwt
10.2.1. Содержимое реестра
В этом разделе в реестре IANA "OAuth URI", учреждённом документом
"An IETF URN Sub-Namespace for OAuth" [RFC6755], регистрируется
значение "token-type:jwt", которое можно использовать для указания
того, что содержимое является JWT.
o URN: urn:ietf:params:oauth:token-type:jwt
o Общее название: JSON Web Token (JWT) Token Type
o Ответственный за изменения: IESG
o Документ(ы) спецификации: RFC 7519
10.3. Регистрация типа мультимедиа
10.3.1. Содержимое реестра
В этом разделе в реестре "Media Types" [IANA.MediaTypes] способом,
описанным в RFC 6838 [RFC6838], регистрируется тип мультимедиа
"application/jwt" [RFC2046], который можно использовать для указания
того, что содержимое является JWT.
o Имя типа: application
o Имя подтипа: jwt
o Обязательные параметры: n/a
o Необязательные параметры: n/a
o Соображения относительно кодирования: 8bit; значения JWT кодируются
как последовательность значений, закодированных с помощью base64url
(некоторые из них могут быть пустой строкой), разделённых символами
точки ('.').
o Соображения безопасности: см. раздел «Соображения безопасности»
RFC 7519
o Соображения совместимости: n/a
o Опубликованная спецификация: RFC 7519
o Приложения, использующие этот тип мультимедиа: OpenID Connect, Mozilla
Persona, Salesforce, Google, Android, Windows Azure, Amazon Web
Services и многие другие
o Соображения относительно идентификаторов фрагментов: n/a
o Дополнительная информация:
Магическое число (числа): n/a
Расширение (расширения) файла: n/a
Код(ы) типа файла Macintosh: n/a
o Контактное лицо и адрес электронной почты для получения
дополнительной информации:
Michael B. Jones, mbj@microsoft.com
o Предполагаемое использование: COMMON
o Ограничения на использование: отсутствуют
o Автор: Michael B. Jones, mbj@microsoft.com
o Ответственный за изменения: IESG
o Предварительная регистрация? Нет
10.4. Регистрация имён параметров заголовка
В этом разделе определённые имена утверждений из раздела 4.1
регистрируются в реестре IANA "JSON Web Signature and Encryption
Header Parameters", учреждённом [JWS], для использования утверждениями,
дублируемыми в качестве параметров заголовка в JWE согласно разделу 5.3.
10.4.1. Содержимое реестра
o Имя параметра заголовка: "iss"
o Описание параметра заголовка: издатель
o Место (места) использования параметра заголовка: JWE
o Ответственный за изменения: IESG
o Документ(ы) спецификации: раздел 4.1.1 RFC 7519
o Имя параметра заголовка: "sub"
o Описание параметра заголовка: субъект
o Место (места) использования параметра заголовка: JWE
o Ответственный за изменения: IESG
o Документ(ы) спецификации: раздел 4.1.2 RFC 7519
o Имя параметра заголовка: "aud"
o Описание параметра заголовка: аудитория
o Место (места) использования параметра заголовка: JWE
o Ответственный за изменения: IESG
o Документ(ы) спецификации: раздел 4.1.3 RFC 7519
11. Соображения безопасности
Агенты JWT/JWS/JWE/JWK должны решать все вопросы безопасности,
относящиеся к любому криптографическому приложению. К числу этих
вопросов относятся защита закрытых ключей пользователя для
асимметричной криптографии и его секретных симметричных ключей,
а также применение мер противодействия различным атакам.
Все соображения безопасности из спецификации JWS также применимы
к JWT, как и соображения безопасности JWE, когда используется
шифрование. В частности, разделы 10.12 («Соображения безопасности
JSON») и 10.13 («Соображения безопасности при сравнении Unicode»)
[JWS] в равной мере применимы к набору утверждений JWT тем же
образом, что и к заголовку JOSE.
11.1. Решения о доверии
На содержимое JWT нельзя полагаться при принятии решения о доверии,
если оно не защищено криптографическими средствами или не привязано
к контексту, необходимому для принятия такого решения. В частности,
обычно потребуется возможность проверить, что ключ(и), используемые
для подписания и/или шифрования JWT, находятся под контролем стороны,
указанной в качестве издателя JWT.
11.2. Порядок подписания и шифрования
Хотя с точки зрения синтаксиса операции подписания и шифрования для
вложенных JWT могут применяться в любом порядке, если необходимы
и подписание, и шифрование, создателям обычно следует подписывать
сообщение, а затем
шифровать результат (тем самым шифруя подпись). Это предотвращает
атаки, при которых подпись удаляется и остаётся лишь зашифрованное
сообщение, а также обеспечивает приватность подписанта. Кроме того,
во многих юрисдикциях подписи зашифрованного текста не считаются
действительными.
Обратите внимание, что потенциальные проблемы безопасности,
связанные с порядком операций подписания и шифрования, уже учтены
в базовых спецификациях JWS и JWE; в частности, поскольку JWE
поддерживает только использование алгоритмов аутентифицированного
шифрования, криптографические соображения относительно возможной
необходимости подписания после шифрования, применимые во многих
контекстах, к этой спецификации не применимы.
12. Соображения приватности
JWT может содержать информацию, чувствительную с точки зрения
приватности. В таком случае ДОЛЖНЫ (MUST) быть приняты меры,
предотвращающие раскрытие этой информации сторонам, которым она
не предназначена. Один из способов добиться этого — использовать
зашифрованный JWT и аутентифицировать получателя. Другой способ —
обеспечить передачу JWT, содержащих незашифрованную информацию,
чувствительную с точки зрения приватности, только по протоколам,
использующим шифрование и поддерживающим аутентификацию конечных
точек, таким как Transport Layer Security (TLS). Исключение из JWT
информации, чувствительной с точки зрения приватности, — простейший
способ свести проблемы приватности к минимуму.
13.1. Нормативные ссылки
[ECMAScript]
Ecma International, "ECMAScript Language Specification,
5.1 Edition", ECMA Standard 262, June 2011,
<http://www.ecma-international.org/ecma-262/5.1/
ECMA-262.pdf>.
[IANA.MediaTypes]
IANA, "Media Types",
<http://www.iana.org/assignments/media-types>.
[JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015,
<http://www.rfc-editor.org/info/rfc7518>.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015,
<http://www.rfc-editor.org/info/rfc7516>.
[JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC, May 2015,
<http://www.rfc-editor.org/info/rfc7515>.
[RFC20] Cerf, V., "ASCII format for Network Interchange", STD 80,
RFC 20, DOI 10.17487/RFC0020, October 1969,
<http://www.rfc-editor.org/info/rfc20>.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
DOI 10.17487/RFC2046, November 1996,
<http://www.rfc-editor.org/info/rfc2046>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC4949] Shirey, R., "Internet Security Glossary, Version 2",
FYI 36, RFC 4949, DOI 10.17487/RFC4949, August 2007,
<http://www.rfc-editor.org/info/rfc4949>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <http://www.rfc-editor.org/info/rfc7159>.
[UNICODE] The Unicode Consortium, "The Unicode Standard",
<http://www.unicode.org/versions/latest/>.
13.2. Информационные ссылки
[CanvasApp]
Facebook, "Canvas Applications", 2010,
<http://developers.facebook.com/docs/authentication/
canvas>.
[JSS] Bradley, J. and N. Sakimura (editor), "JSON Simple Sign",
September 2010, <http://jsonenc.info/jss/1.0/>.
[MagicSignatures]
Panzer, J., Ed., Laurie, B., and D. Balfanz, "Magic
Signatures", January 2011,
<http://salmon-protocol.googlecode.com/svn/
trunk/draft-panzer-magicsig-01.html>.
[OASIS.saml-core-2.0-os]
Cantor, S., Kemp, J., Philpott, R., and E. Maler,
"Assertions and Protocols for the OASIS Security Assertion
Markup Language (SAML) V2.0", OASIS Standard
saml-core-2.0-os, March 2005,
<http://docs.oasis-open.org/security/saml/v2.0/
saml-core-2.0-os.pdf>.
[POSIX.1] IEEE, "The Open Group Base Specifications Issue 7", IEEE
Std 1003.1, 2013 Edition, 2013,
<http://pubs.opengroup.org/onlinepubs/9699919799/
basedefs/V1_chap04.html#tag_04_15>.
[RFC3275] Eastlake 3rd, D., Reagle, J., and D. Solo, "(Extensible
Markup Language) XML-Signature Syntax and Processing",
RFC 3275, DOI 10.17487/RFC3275, March 2002,
<http://www.rfc-editor.org/info/rfc3275>.
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<http://www.rfc-editor.org/info/rfc3339>.
[RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
Unique IDentifier (UUID) URN Namespace", RFC 4122,
DOI 10.17487/RFC4122, July 2005,
<http://www.rfc-editor.org/info/rfc4122>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>.
[RFC6755] Campbell, B. and H. Tschofenig, "An IETF URN Sub-Namespace
for OAuth", RFC 6755, DOI 10.17487/RFC6755, October 2012,
<http://www.rfc-editor.org/info/rfc6755>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<http://www.rfc-editor.org/info/rfc6838>.
[SWT] Hardt, D. and Y. Goland, "Simple Web Token (SWT)", Version
0.9.5.1, November 2009, <http://msdn.microsoft.com/en-us/
library/windowsazure/hh781551.aspx>.
[W3C.CR-xml11-20060816]
Cowan, J., "Extensible Markup Language (XML) 1.1 (Second
Edition)", World Wide Web Consortium Recommendation
REC-xml11-20060816, August 2006,
<http://www.w3.org/TR/2006/REC-xml11-20060816>.
[W3C.REC-xml-c14n-20010315]
Boyer, J., "Canonical XML Version 1.0", World Wide Web
Consortium Recommendation REC-xml-c14n-20010315, March
2001, <http://www.w3.org/TR/2001/REC-xml-c14n-20010315>.
Приложение A. Примеры JWT
Этот раздел содержит примеры JWT. Другие примеры JWT см. в разделе 6.1
этого документа и приложениях A.1–A.3 [JWS].
A.1. Пример зашифрованного JWT
В этом примере те же утверждения, что использованы в разделе 3.1,
шифруются для получателя с использованием RSAES-PKCS1-v1_5
и AES_128_CBC_HMAC_SHA_256.
Следующий пример заголовка JOSE объявляет, что:
o Ключ шифрования содержимого шифруется для получателя с использованием
алгоритма RSAES-PKCS1-v1_5 для получения зашифрованного ключа JWE.
o К открытому тексту применяется аутентифицированное шифрование
с использованием алгоритма AES_128_CBC_HMAC_SHA_256 для получения
шифротекста JWE и тега аутентификации JWE.
{"alg":"RSA1_5","enc":"A128CBC-HS256"}
За исключением использования октетов представления набора утверждений
JWT из раздела 3.1 в UTF-8 в качестве значения открытого текста,
вычисление этого JWT идентично вычислению JWE в приложении A.2 [JWE],
в том числе в отношении используемых ключей.
Конечный результат в этом примере (переносы строк добавлены только
для отображения):
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.
QR1Owv2ug2WyPBnbQrRARTeEk9kDO2w8qDcjiHnSJflSdv1iNqhWXaKH4MqAkQtM
oNfABIPJaZm0HaA415sv3aeuBWnD8J-Ui7Ah6cWafs3ZwwFKDFUUsWHSK-IPKxLG
TkND09XyjORj_CHAgOPJ-Sd8ONQRnJvWn_hXV1BNMHzUjPyYwEsRhDhzjAD26ima
sOTsgruobpYGoQcXUwFDn7moXPRfDE8-NoQX7N7ZYMmpUDkR-Cx9obNGwJQ3nM52
YCitxoQVPzjbl7WBuB7AohdBoZOdZ24WlN1lVIeh8v1K4krB8xgKvRU8kgFrEn_a
1rZgN5TiysnmzTROF869lQ.
AxY8DCtDaGlsbGljb3RoZQ.
MKOle7UQrG6nSxTLX6Mqwt0orbHvAKeWnDYvpIAeZ72deHxz3roJDXQyhxx0wKaM
HDjUEOKIwrtkHthpqEanSBNYHZgmNOV7sln1Eu9g3J8.
fiK51VwhsxJ-siBMR-YFiA
A.2. Пример вложенного JWT
Этот пример показывает, как JWT можно использовать в качестве полезной
нагрузки JWE или JWS для создания вложенного JWT. В данном случае набор
утверждений JWT сначала подписывается, а затем шифруется.
Внутренний подписанный JWT идентичен примеру в приложении A.2 документа
[JWS]. Поэтому его вычисление здесь не повторяется. Затем в этом примере
внутренний JWT шифруется для получателя с использованием
RSAES-PKCS1-v1_5 и AES_128_CBC_HMAC_SHA_256.
Приведённый ниже пример заголовка JOSE объявляет следующее:
o Ключ шифрования содержимого шифруется для получателя с использованием
алгоритма RSAES-PKCS1-v1_5, в результате чего получается зашифрованный
ключ JWE.
o К открытому тексту применяется аутентифицированное шифрование с
использованием алгоритма AES_128_CBC_HMAC_SHA_256, в результате чего
получаются шифротекст JWE и тег аутентификации JWE.
o Открытый текст сам является JWT.
{"alg":"RSA1_5","enc":"A128CBC-HS256","cty":"JWT"}
Кодирование октетов UTF-8-представления заголовка JOSE в base64url даёт
следующее значение закодированного заголовка JOSE:
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldUIn0
Вычисление этого JWT идентично вычислению JWE в приложении A.2 документа
[JWE], за исключением того, что используются другие значения заголовка
JOSE, открытого текста, вектора инициализации JWE и ключа шифрования
содержимого. (Используется тот же ключ RSA.)
В качестве открытого текста используются октеты ASCII-представления
[RFC20] JWT, приведённого в конце приложения A.2.1 документа [JWS]
(с удалением всех пробельных символов и разрывов строк); это
последовательность из 458 октетов.
Используемое значение вектора инициализации JWE (в записи в виде
массива JSON):
[82, 101, 100, 109, 111, 110, 100, 32, 87, 65, 32, 57, 56, 48, 53,
50]
В этом примере используется ключ шифрования содержимого, представленный
следующим значением в кодировке base64url:
GawgguFyGrWKav7AX4VKUg
Окончательный результат для этого вложенного JWT (разрывы строк добавлены
только для отображения):
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiY3R5IjoiSldU
In0.
g_hEwksO1Ax8Qn7HoN-BVeBoa8FXe0kpyk_XdcSmxvcM5_P296JXXtoHISr_DD_M
qewaQSH4dZOQHoUgKLeFly-9RI11TG-_Ge1bZFazBPwKC5lJ6OLANLMd0QSL4fYE
b9ERe-epKYE3xb2jfY1AltHqBO-PM6j23Guj2yDKnFv6WO72tteVzm_2n17SBFvh
DuR9a2nHTE67pe0XGBUS_TK7ecA-iVq5COeVdJR4U4VZGGlxRGPLRHvolVLEHx6D
YyLpw30Ay9R6d68YCLi9FYTq3hIXPK_-dmPlOUlKvPr1GgJzRoeC9G5qCvdcHWsq
JGTO_z3Wfo5zsqwkxruxwA.
UmVkbW9uZCBXQSA5ODA1Mg.
VwHERHPvCNcHHpTjkoigx3_ExK0Qc71RMEParpatm0X_qpg-w8kozSjfNIPPXiTB
BLXR65CIPkFqz4l1Ae9w_uowKiwyi9acgVztAi-pSL8GQSXnaamh9kX1mdh3M_TT
-FZGQFQsFhu0Z72gJKGdfGE-OE7hS1zuBD5oEUfk0Dmb0VzWEzpxxiSSBbBAzP10
l56pPfAtrjEYw-7ygeMkwBl6Z_mLS6w6xUgKlvW6ULmkV-uLC4FUiyKECK4e3WZY
Kw1bpgIqGYsw2v_grHjszJZ-_I5uM-9RA8ycX9KqPRp9gc6pXmoU_-27ATs9XCvr
ZXUtK2902AUzqpeEUJYjWWxSNsS-r1TJ1I-FMJ4XyAiGrfmo9hQPcNBYxPz3GQb2
8Y5CLSQfNgKSGt0A4isp1hBUXBHAndgtcslt7ZoQJaKe_nNJgNliWtWpJ_ebuOpE
l8jdhehdccnRMIwAmU1n7SPkmhIl1HlSOpvcvDfhUN5wuqU955vOBvfkBOh5A11U
zBuo2WlgZ6hYi9-e3w29bR0C2-pp3jbqxEDw3iWaf2dc5b-LnR0FEYXvI_tYk5rd
_J9N0mg0tQ6RbpxNEMNoA9QWk5lgdPvbh9BaO195abQ.
AVO9iT5AV4CzvDJCdhSFlQ
Приложение B. Соотношение JWT и утверждений SAML
Security Assertion Markup Language (SAML) 2.0
[OASIS.saml-core-2.0-os] предоставляет стандарт создания токенов
безопасности с большей выразительностью и более широким выбором
средств безопасности, чем поддерживают JWT. Однако за эту гибкость и
выразительность приходится платить как размером, так и сложностью.
Использование в SAML XML [W3C.CR-xml11-20060816] и XML Digital Signature
(DSIG) [RFC3275] способствует увеличению размера утверждений SAML;
использование XML и особенно каноникализации XML
[W3C.REC-xml-c14n-20010315] способствует повышению их сложности.
JWT предназначены для предоставления простого формата токенов
безопасности, достаточно компактного для размещения в заголовках HTTP
и аргументах запроса в URI. Это достигается поддержкой гораздо более
простой модели токена, чем в SAML, и использованием синтаксиса
кодирования объектов JSON [RFC7159]. Формат также поддерживает защиту
токенов с помощью кодов аутентификации сообщений (MAC) и цифровых
подписей с использованием более компактного (и менее гибкого) формата,
чем XML DSIG.
Таким образом, хотя JWT могут выполнять некоторые из тех же функций,
что и утверждения SAML, JWT предназначены не для полной замены
утверждений SAML, а для использования в качестве формата токенов в
случаях, когда важны простота реализации или компактность.
Утверждения SAML всегда являются высказываниями некоторой сущности о
субъекте. JWT часто используются таким же образом: сущность, делающая
высказывания, представлена утверждением "iss" (издатель), а субъект —
утверждением "sub" (субъект). Однако, поскольку эти утверждения
необязательны, допускаются и другие способы использования формата JWT.
Приложение C. Соотношение JWT и Simple Web Tokens (SWT)
И JWT, и SWT [SWT] по своей сути позволяют передавать наборы утверждений
между приложениями. В SWT как имена утверждений, так и их значения
являются строками. В JWT имена утверждений являются строками, а значения
утверждений могут иметь любой тип JSON. Оба типа токенов обеспечивают
криптографическую защиту своего содержимого: SWT — с помощью HMAC
SHA-256, а JWT — с возможностью выбора алгоритмов, включая алгоритмы
подписи, MAC и шифрования.