GenerateJWT ポリシー

概要

構成可能な一連のクレームを含む、署名付きの JWT を生成します。JWT はクライアントに返すことができます。また、バックエンド ターゲットに送信するなど、他の方法で使用することもできます。詳細については、JWS ポリシーと JWT ポリシーの概要をご覧ください。

動画

署名付きの JWT を生成する方法について、短い動画をご覧ください。

サンプル

• HS256 アルゴリズムで署名された JWT を生成する
• RS256 アルゴリズムで署名された JWT を生成する

HS256 アルゴリズムで署名された JWT を生成する

このポリシー サンプルでは、新しい JWT を生成し、HS256 アルゴリズムを使用して署名します。HS256 は、署名とその検証の両方に共有シークレットを利用します。

このポリシー アクションがトリガーされると、Edge は JWT ヘッダーとペイロードをエンコードし、JWT にデジタル署名します。ポリシーに対してリクエストする方法など、詳しい例については上記の動画をご覧ください。

このサンプルのポリシー構成は、JWT 仕様で定義されている一連の標準的なクレーム（これには有効期間 1 時間のクレームも含まれます）と、追加クレーム 1 つからなる 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 の各クレームの値は生成されるたびに変わります。

RS256 アルゴリズムで署名された JWT を生成する

このポリシー サンプルでは、新しい 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>

Generate JWT の要素リファレンス

このポリシー リファレンスでは、Generate JWT ポリシーの要素と属性について説明しています。

注: 構成は使用する暗号化アルゴリズムにより異なります。特定のユースケースの構成例については、サンプルをご覧ください。

最上位の要素に適用される属性

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

次の属性は、すべてのポリシーの親要素に共通です。

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別の自然言語名でラベルを付けるために使います。

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

トークンに署名する暗号化アルゴリズムを指定します。

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

ポリシーは、指定された値に設定された aud クレームを含む JWT を生成します。このクレームは、この JWT を受け取ると想定された対象を識別します。これは、RFC7519 に記載されている登録済みクレームの 1 つです。

<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 属性と明示的なクレーム値が両方指定された場合、明示的な値がデフォルトとなり、参照されたフロー変数が解決されない場合に使用されます。
• type -（省略可）文字列（デフォルト）、数値、ブール値、マッピングのいずれか
• 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 属性と明示的なクレーム値が両方指定された場合、明示的な値がデフォルトとなり、参照されたフロー変数が解決されない場合に使用されます。
• type -（省略可）文字列（デフォルト）、数値、ブール値、マッピングのいずれか
• 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 ヘッダーにリストされたヘッダーごとに、VerifyJWT ポリシーの <KnownHeaders> 要素もそのヘッダーにリストされていることが確認されます。ポリシーが crit で検出したヘッダーの中に <KnownHeaders> にリストされていないものがあると、VerifyJWT ポリシーは失敗します。

<CustomClaims>

注: 現在、UI を使用して新しい GenerateJWT ポリシーを追加すると CustomClaims 要素が挿入されます。この要素は機能していないため無視されます。代わりに使用する要素は <AdditionalClaims> です。あとで正しい要素が挿入されるように UI が更新されます。

<ExpiresIn>

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

JWT の寿命を、ミリ秒、秒、分、時、日で指定します。

<Id>

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

特定の jti クレームを持つ JWT を生成します。text 値と ref 属性が両方とも空白の場合、ポリシーはランダムな UUID を含む jti を生成します。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>

ポリシーは、iss というクレームを含む JWT を生成します。この値は指定した値に設定されます。JWT の発行者を識別するクレームで、RFC7519 に記載されている登録済みクレームの 1 つです。

<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 要素で有効な時間値

相対時間値の場合は、整数と期間を指定します。次に例を示します。

• 10s
• 60m
• 12h

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

JWT ヘッダーに含めるキー ID（子）を指定します。アルゴリズムが 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>

JWT への署名に使用され、PEM エンコードされた秘密鍵を指定します。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>

HMAC アルゴリズムで署名された JWT の JWT ヘッダーに含めるキー ID（子）を指定します。アルゴリズムが HS256、HS384、HS512 のいずれかの場合にのみ使用します。

<SecretKey/Value>

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

HMAC アルゴリズムでトークンを検証するかトークンに署名するための秘密鍵です。アルゴリズムが HS256、HS384、HS512 のいずれかの場合にのみ使用します。ref 属性を使用して、鍵をフロー変数に渡します。

HS256 / HS384 / HS512 アルゴリズムの場合は、Edge による鍵の最小長の制限があります。鍵の最小長は、HS256 では 32 バイト、HS384 では 48 バイト、HS512 では 64 バイトです。強度の低い鍵を使用すると実行時エラーが発生します。

<Subject>

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

<Subject ref="flow_variable" />

例:

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

ポリシーは、指定された値に設定された sub クレームを含む JWT を生成します。これは、RFC7519 に記載されている標準的なクレームの 1 つです。

フロー変数

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>