Создать политику JWT

Вы просматриваете документацию Apigee Edge .
Перейдите к документации Apigee X. информация

Что

Создает подписанный JWT с настраиваемым набором утверждений. Затем JWT можно вернуть клиентам, передать на серверные цели или использовать другими способами. Подробное описание см. в обзоре политик JWS и JWT .

Видео

Посмотрите короткое видео, чтобы узнать, как создать подписанный JWT.

Образцы

• Создайте JWT, подписанный с помощью алгоритма HS256.
• Создайте JWT, подписанный с помощью алгоритма RS256.

Создайте JWT, подписанный с помощью алгоритма HS256.

В этом примере политики создается новый JWT и подписывается его с использованием алгоритма HS256. HS256 использует общий секрет как для подписания, так и для проверки подписи.

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

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

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Результирующий JWT будет иметь этот заголовок…

{
  "typ" : "JWT", 
  "alg" : "HS256",
  "kid" : "1918290"
}

… и будет иметь полезную нагрузку примерно такого содержания:

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

Значение утверждений iat , exp и jti будет различаться.

Создайте JWT, подписанный с помощью алгоритма RS256.

В этом примере политики создается новый JWT и подписывается его с использованием алгоритма RS256. Генерация подписи RS256 основана на секретном ключе RSA, который должен быть предоставлен в форме, закодированной PEM. Полный пример смотрите в видеоролике выше, в том числе о том, как сделать запрос в политику.

Когда это действие политики срабатывает, Edge кодирует и подписывает цифровой подписью JWT, включая утверждения. Чтобы узнать о частях JWT, а также о том, как они шифруются и подписываются, обратитесь к RFC7519 .

<GenerateJWT name="JWT-Generate-RS256">
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

Настройка ключевых элементов

Элементы, которые вы используете для указания ключа, используемого для создания JWT, зависят от выбранного алгоритма, как показано в следующей таблице:

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Ссылка на элемент для создания JWT

Справочник по политике описывает элементы и атрибуты политики «Создать JWT».

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

Атрибуты, которые применяются к элементу верхнего уровня

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

Следующие атрибуты являются общими для всех родительских элементов политики.

<ОтображаемоеИмя>

<DisplayName>Policy Display Name</DisplayName>

Используйте в дополнение к атрибуту name, чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<Алгоритм>

<Algorithm>algorithm-here</Algorithm>

Указывает алгоритм шифрования для подписи токена.

<Аудитория>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

Политика создает JWT, содержащий утверждение аудита , которому присвоено указанное значение. Это утверждение идентифицирует получателей, для которых предназначен JWT. Это одно из зарегистрированных утверждений, упомянутых в RFC7519 .

<Дополнительные утверждения/заявки>

<AdditionalClaims>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

Позволяет указать дополнительные пары имя/значение утверждения в полезных данных JWT. Вы можете явно указать утверждение в виде строки, числа, логического значения, карты или массива. Карта — это просто набор пар имя/значение.

Элемент <Claim> принимает следующие атрибуты:

• name — (Обязательно) Имя претензии.
• ref — (Необязательно) Имя переменной потока. Если она присутствует, политика будет использовать значение этой переменной в качестве утверждения. Если указаны и атрибут ref , и явное значение утверждения, явное значение является значением по умолчанию и используется, если указанная переменная потока неразрешена.
• тип — (необязательно) Одно из: строка (по умолчанию), число, логическое значение или карта.
• массив — (необязательно). Установите значение true , чтобы указать, является ли значение массивом типов. По умолчанию: ложь.

Если вы включите элемент <Claim> , имена утверждений задаются статически при настройке политики. Альтернативно вы можете передать объект JSON, чтобы указать имена утверждений. Поскольку объект JSON передается как переменная, имена утверждений в созданном JWT определяются во время выполнения.

Например:

<AdditionalClaims ref='json_claims'/>

Где переменная json_claims содержит объект JSON в форме:

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

Созданный JWT включает все утверждения в объекте JSON.

<Дополнительные заголовки/утверждение>

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

Помещает дополнительные пары имя/значение утверждения в заголовок JWT.

Элемент <Claim> принимает следующие атрибуты:

• name — (Обязательно) Имя претензии.
• ref — (Необязательно) Имя переменной потока. Если она присутствует, политика будет использовать значение этой переменной в качестве утверждения. Если указаны и атрибут ref , и явное значение утверждения, явное значение является значением по умолчанию и используется, если указанная переменная потока неразрешена.
• тип — (необязательно) Одно из: строка (по умолчанию), число, логическое значение или карта.
• массив — (необязательно). Установите значение true , чтобы указать, является ли значение массивом типов. По умолчанию: ложь.

<Критические заголовки>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

Добавляет критический заголовок crit в заголовок JWT. Критический заголовок — это массив имен заголовков, которые должны быть известны и распознаны получателем JWT. Например:

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

Во время выполнения политика VerifyJWT проверяет критический заголовок. Для каждого элемента, указанного в критическом заголовке, он проверяет, что элемент <KnownHeaders> политики VerifyJWT также содержит этот заголовок. Любой заголовок, который политика VerifyJWT обнаруживает в критическом состоянии и который также не указан в <KnownHeaders> , приводит к сбою политики VerifyJWT.

<CustomClaims>

Примечание. В настоящее время элемент CustomClaims вставляется при добавлении новой политики GenerateJWT через пользовательский интерфейс. Этот элемент не функционален и игнорируется. Вместо этого правильнее использовать элемент <AdditionalClaims> . Пользовательский интерфейс будет обновлен для вставки правильных элементов позже.

<Истекает>

<ExpiresIn>time-value-here</ExpiresIn>

Указывает срок жизни JWT в миллисекундах, секундах, минутах, часах или днях.

<Идентификатор>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

Создает JWT с конкретным утверждением jti. Если текстовое значение и атрибут ref пусты, политика сгенерирует jti, содержащий случайный UUID. Утверждение JWT ID (jti) — это уникальный идентификатор JWT. Дополнительную информацию о jti можно найти в RFC7519 .

<Игнорировать неразрешенные переменные>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Эмитент>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

Политика создает JWT, содержащий утверждение с именем iss и значением, равным указанному значению. Утверждение, идентифицирующее эмитента JWT. Это один из зарегистрированных наборов утверждений, упомянутых в RFC7519 .

<НеПрежде>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

Указывает время, когда токен становится действительным. Токен недействителен до указанного времени. Вы можете указать либо абсолютное значение времени, либо время относительно момента создания токена.

Допустимые значения времени для элемента NotBefore для значений абсолютного времени.

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

• 10 с
• 60 м
• 12 часов

<Выходная переменная>

<OutputVariable>jwt-variable</OutputVariable>

Указывает, где разместить JWT, созданный этой политикой. По умолчанию он помещается в переменную потока jwt. POLICYNAME .generated_jwt .

<Частный ключ/идентификатор>

<PrivateKey>
  <Id ref="flow-variable-name-here"/>
</PrivateKey>

or

<PrivateKey>
  <Id>your-id-value-here</Id>
</PrivateKey>

Указывает идентификатор ключа (ребенок), который нужно включить в заголовок JWT. Используйте только в том случае, если используется один из алгоритмов: RS256/RS384/RS512, PS256/PS384/PS512 или ES256/ES384/ES512.

<Частный ключ/пароль>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

Укажите пароль, который политика должна использовать для расшифровки закрытого ключа, если это необходимо. Используйте атрибут ref для передачи ключа в переменной потока. Используйте только в том случае, если используется один из алгоритмов: RS256/RS384/RS512, PS256/PS384/PS512 или ES256/ES384/ES512.

<Частный ключ/значение>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

Указывает закрытый ключ в формате PEM, используемый для подписи JWT. Используйте атрибут ref для передачи ключа в переменной потока. Используйте только в том случае, если используется один из алгоритмов: RS256/RS384/RS512, PS256/PS384/PS512 или ES256/ES384/ES512.

<Секретный ключ/идентификатор>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

Указывает идентификатор ключа (kid), который необходимо включить в заголовок JWT файла JWT, подписанного с помощью алгоритма HMAC. Используйте только в том случае, если используется один из алгоритмов HS256/HS384/HS512.

<Секретный ключ/значение>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

Предоставляет секретный ключ, используемый для проверки или подписи токенов с помощью алгоритма HMAC. Используйте только в том случае, если используется один из алгоритмов HS256/HS384/HS512. Используйте атрибут ref для передачи ключа в переменной потока.

Edge обеспечивает минимальную стойкость ключа для алгоритмов HS256/HS384/HS512. Минимальная длина ключа для HS256 — 32 байта, для HS384 — 48 байт, а для HS512 — 64 байта. Использование ключа более низкого уровня вызывает ошибку во время выполнения.

<Тема>

<Subject>subject-string-here</Subject>

<Subject ref="flow_variable" />

Например:

<Subject ref="apigee.developer.email"/>

Политика создает JWT, содержащий вложенное утверждение, которому присвоено указанное значение. Это утверждение идентифицирует или делает заявление о предмете JWT. Это один из стандартных наборов утверждений, упомянутых в RFC7519 .

Переменные потока

Политика «Создать JWT» не устанавливает переменные потока.

Ссылка на ошибку

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются Edge, когда эта политика вызывает ошибку. Эту информацию важно знать, если вы разрабатываете правила обработки ошибок. Дополнительные сведения см. в разделах Что нужно знать об ошибках политики и Обработка ошибок .

Ошибки выполнения

Эти ошибки могут возникнуть при выполнении политики.

Ошибки развертывания

Эти ошибки могут возникнуть при развертывании прокси-сервера, содержащего эту политику.

Переменные неисправности

Эти переменные устанавливаются при возникновении ошибки во время выполнения. Дополнительные сведения см. в разделе Что нужно знать об ошибках политики .

Пример ответа об ошибке

Для обработки ошибок лучше всего перехватывать часть errorcode в ответе на ошибку. Не полагайтесь на текст в faultstring , поскольку он может измениться.

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

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>