Правило GenerateJWT

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

Что

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

Видео

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

Примеры

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

Как создать токен JWT, подписанный алгоритмом HS256

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

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

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

<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"

В справочнике по правилам описаны элементы и атрибуты правила Generate JWT.

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

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

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

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

<AdditionalClaims/Claim>

<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, и явное значение утверждения, то по умолчанию используется явное значение. Оно также будет использоваться, если не удастся разрешить переменную потока, на которую ссылается атрибут ref.
• type – (необязательно) один из следующих вариантов: string (строка, по умолчанию), number (число), boolean (логическое значение) или map (карта).
• array – (необязательный параметр) установите значение true, чтобы указать, является ли значение массивом типов. Значение по умолчанию – false.

Если вы добавите элемент <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>

<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, и явное значение утверждения, то по умолчанию используется явное значение. Оно также будет использоваться, если не удастся разрешить переменную потока, на которую ссылается атрибут ref.
• type – (необязательно) один из следующих вариантов: string (строка, по умолчанию), number (число), boolean (логическое значение) или map (карта).
• array – (необязательный параметр) установите значение true, чтобы указать, является ли значение массивом типов. Значение по умолчанию – false.

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

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

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

Во время выполнения правило VerifyJWT проверяет заголовок crit. Для каждого элемента, указанного в заголовке crit, проверяется, есть ли этот заголовок в элементе <KnownHeaders> правила VerifyJWT. Если в заголовке, который политика VerifyJWT находит в crit, нет записи в <KnownHeaders>, политика VerifyJWT завершается с ошибкой.

<CustomClaims>

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

<ExpiresIn>

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

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

<Id>

<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>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

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

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

<NotBefore>

<!-- 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>

<OutputVariable>jwt-variable</OutputVariable>

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

<PrivateKey/Id>

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

or

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

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

<PrivateKey/Password>

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

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

<PrivateKey/Value>

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

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

<SecretKey/Id>

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

or

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

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

<SecretKey/Value>

<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>subject-string-here</Subject>

<Subject ref="flow_variable" />

Пример:

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

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

Переменные процесса

Правило Generate 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>