GenerateSAMLAssertion ポリシー

拡張可能なポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する

GenerateSAMLAssertion ポリシーを使用すると、API プロキシで SAML アサーションを送信 XML リクエストに追加できます。これらのアサーションは、バックエンド サービスが認証と認可用の追加のセキュリティ処理を適用するために使用できます。詳細については、SAML ポリシーの概要をご覧ください。

このポリシーは拡張可能なポリシーであり、Apigee ライセンスによっては、このポリシーの使用によって費用や使用量に影響する場合があります。ポリシータイプと使用量への影響については、ポリシータイプをご覧ください。

サンプル

<GenerateSAMLAssertion name="SAML" ignoreContentType="false">
  <CanonicalizationAlgorithm />
  <Issuer ref="reference">Issuer name</Issuer>
  <KeyStore>
    <Name ref="reference">keystorename</Name>
    <Alias ref="reference">alias</Alias>
  </KeyStore>
  <OutputVariable>
    <FlowVariable>assertion.content</FlowVariable>
    <Message name="request">
      <Namespaces>
        <Namespace prefix="soap">http://schemas.xmlsoap.org/soap/envelope/</Namespace>
        <Namespace prefix='wsse'>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</Namespace>
      </Namespaces>
      <XPath>/soap:Envelope/soap:Header/wsse:Security</XPath>
    </Message>
  </OutputVariable>
  <SignatureAlgorithm />
  <Subject ref="reference">Subject name</Subject>
  <Template ignoreUnresolvedVariables="false">
    <!-- A lot of XML goes here, within CDATA, with {} around
         each variable -->
  </Template>
</GenerateSAMLAssertion>

要素リファレンス

このセクションでは、GenerateSAMLAssertion ポリシーの要素と属性について説明します。

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

<GenerateSAMLAssertion name="SAML-A1" continueOnError="false" enabled="true" async="false">

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

属性	説明	デフォルト	要否
name	ポリシーの内部名。名前に使用できる文字は A-Z0-9._\-$ % のみです。ただし、Apigee UI には追加の制限があり、たとえば、英数字以外の文字は自動的に削除されます。 必要に応じて、<displayname></displayname> 要素を使用して、Apigee UI プロキシ エディタでポリシーに別の自然言語名でラベルを付けます。	なし	必須
有効	ポリシーを適用するには、true に設定します。 ポリシーを「turn off」するには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。	true	省略可

SAML アサーション生成の要素と属性

フィールド名	説明
ignoreContentType 属性	true または false に設定できるブール値。デフォルトでは、メッセージのコンテンツ タイプが XML Content-Type でない場合、アサーションは生成されません。これが true に設定されている場合、メッセージはコンテンツ タイプに関係なく XML として扱われます。
Issuer	ID プロバイダの固有識別子。オプションの ref 属性が存在する場合は、指定された変数に基づいて発行者の値がランタイムに割り当てられます。オプションの ref 属性が存在しない場合は、発行者の値が使用されます。
KeyStore	SAML アサーションのデジタル署名に使用する秘密鍵とそのエイリアスを含む KeyStore の名前。
OutputVariable	生成された SAML アサーションの配置場所を指定します。アサーションは、フロー変数に保存するか、既存のメッセージに挿入できます。
FlowVariable	生成された SAML アサーション コンテンツが格納されるフロー変数の名前を指定します。これは、<Message> 要素を使用してアサーションを既存の XML メッセージに挿入する方法の代替策です。
Message	ポリシーのターゲット。有効な値は message、request、response です。message に設定すると、ポリシーはポリシーの接続ポイントに基づいて条件付きでメッセージ オブジェクトを取得します。リクエスト フローに接続すると、ポリシーは message をリクエストに解決し、レスポンス フローに接続すると、message をレスポンスに解決します。
XPath	ポリシーが SAML アサーションを追加するアウトバウンド XML ドキュメントの要素を表す XPath 式。
SignatureAlgorithm	SHA1 または SHA256
Subject	SAML アサーションのサブジェクトの固有識別子。オプションの ref 属性が存在する場合、Subject の値は指定された変数に基づいてランタイムに割り当てられます。オプションの ref 属性が存在しない場合は、Subject の値が使用されます。
Template	存在する場合は、このテンプレートを実行し、{} で示されるすべてを対応する変数に置き換えて、結果にデジタル署名して、アサーションを生成します。テンプレートは AssignMessage ポリシールールの後に処理されます。AssignMessage ポリシーをご覧ください。 <Template> 要素は、メッセージ テンプレートという動的文字列置換機能をサポートしています。メッセージ テンプレートは、ポリシーの署名が GenerateSamlAssertion の場合にのみサポートされます。

使用上の注意

ポリシーの処理:

1. メッセージが XML ではなく、ignoreContentType が true に設定されていない場合、障害が発生します。
2. Template が設定されている場合は、AssignMessage ポリシーの説明にあるように、テンプレートを処理します。変数が指定されず、ignoreUnresolvedVariables も設定されていない場合は、エラーが生成されます。
3. Template が設定されていない場合には、Subject と Issuer パラメータの値または参照を含むアサーションを生成します。
4. 指定されたキーを使用して、アサーションに署名します。
5. 指定された XPath でアサーションをメッセージに追加します。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

デプロイエラー

以下のエラーは、このポリシーを含むプロキシをデプロイするときに発生することがあります。

ヒント: エラーの解決にサポートが必要な場合は、「修正」列の をクリックして、詳しいトラブルシューティング情報をご覧ください。

エラー名	原因	修正
SourceNotConfigured	ValidateSAMLAssertion ポリシーの <Source>、<XPath>、<Namespaces>、<Namespace> 要素のうち、1 つ以上が定義されていないか、空白になっています。
TrustStoreNotConfigured	<TrustStore> 要素が空か、ValidateSAMLAssertion ポリシーで指定されていない場合、API プロキシのデプロイが失敗します。有効なトラストストアが必要です。
NullKeyStoreAlias	子要素 <Alias> が空か、GenerateSAMLAssertion ポリシーの <Keystore> 要素で指定されていない場合、API プロキシのデプロイが失敗します。有効なキーストア エイリアスが必要です。
NullKeyStore	子要素 <Name> が空か、GenerateSAMLAssertion ポリシーの <Keystore> 要素で指定されていない場合、API プロキシのデプロイが失敗します。有効なキーストア名が必要です。
NullIssuer	<Issuer> 要素が空か、GenerateSAMLAssertion ポリシーで指定されていない場合、API プロキシのデプロイが失敗します。有効な <Issuer> の値が必要です。

障害変数

ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

変数	説明	例
fault.name="fault_name"	fault_name は障害の名前です。障害名は、障害コードの最後の部分です。	fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed	検証 SAML assertion ポリシー構成の場合、エラーの接頭辞は ValidateSAMLAssertion になります。	GenerateSAMLAssertion.failed = true

エラー レスポンスの例

注: ベスト プラクティスとして、エラー処理でエラー レスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

{
  "fault": {
    "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type",
    "detail": {
      "errorcode": "steps.saml.generate.InvalidMediaTpe"
    }
  }
}

障害ルールの例

<FaultRules>
    <FaultRule name="invalid_saml_rule">
        <Step>
            <Name>invalid-saml</Name>
        </Step>
        <Condition>(GenerateSAMLAssertion.failed = "true")</Condition>
    </FaultRule>
</FaultRules>

関連トピック

変数の抽出: Extract Variables ポリシー