ValidateSAMLAssertion ポリシー

拡張可能なポリシー

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

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

ValidateSAMLAssertion ポリシーを使用すると、API プロキシは、受信 SOAP リクエストに付加された SAML アサーションを検証できます。SAML ポリシーは、デジタル署名された SAML アサーションの入った受信メッセージを検証して無効な場合は拒否し、他のポリシーまたはバックエンド サービス自体がアサーションの情報をさらに検証できるように変数を設定します。詳細については、SAML ポリシーの概要をご覧ください。

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

サンプル

<ValidateSAMLAssertion name="SAML" ignoreContentType="false">
  <Source 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>
      <Namespace prefix='saml'>urn:oasis:names:tc:SAML:2.0:assertion</Namespace>
    </Namespaces>
    <AssertionXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</AssertionXPath>
    <SignedElementXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</SignedElementXPath>
  </Source>
  <TrustStore>TrustStoreName</TrustStore>
  <RemoveAssertion>false</RemoveAssertion>
</ValidateSAMLAssertion>

要素リファレンス

SAML アサーションを検証する

フィールド名 説明
name 属性
ポリシー インスタンスの名前。名前は、組織内で一意にする必要があります。名前に使用できる文字は A-Z0-9._\-$ % のみです。ただし、Apigee UI には、英数字以外の文字は自動的に削除されるなどの追加の制限があります。
ignoreContentType 属性 true または false に設定できるブール値。デフォルトでは、メッセージのコンテンツ タイプが XML Content-Type でない場合、アサーションは検証されません。これが true に設定されている場合、メッセージはコンテンツ タイプに関係なく XML として扱われます。
Source ポリシーのターゲット。有効な値は message、request、response です。message に設定すると、ポリシーはポリシーの接続ポイントに基づいて条件付きでメッセージ オブジェクトを取得します。リクエスト フローに接続すると、ポリシーは message を request に解決し、レスポンス フローに接続すると、message を response に解決します。
XPath
非推奨。Source の子。AssertionXPath と SignedElementXPath を使用します。
AssertionXPath
Source の子。ポリシーが SAML アサーションを抽出するインバウンド XML ドキュメントの要素を表す XPath 式。
SignedElementXPath
Source の子。ポリシーが署名付き要素を抽出できるインバウンド XML ドキュメントの要素を示す XPath 式。これは、AssertionXPath の XPath とは異なる場合もあれば、同じ場合もあります。
TrustStore
信頼された X.509 証明書を含むトラストストアの名前。この証明書は、SAML アサーションのデジタル署名の検証に使用されます。
RemoveAssertion
true または false に設定できるブール値。true の場合、メッセージがバックエンド サービスに転送される前に、SAML アサーションがリクエスト メッセージから削除されます。

使用上の注意

ポリシーの処理:

  1. インバウンド メッセージを確認し、コンテンツ タイプが text/(.*+)?xml または application/(.*+)?xml と一致する場合、リクエストのメディアタイプが XML であることを確認します。メディアタイプが XML ではなく、ignoreContentType 属性が true に設定されていない場合、エラーを発生させます。
  2. XML を解析します。解析に失敗した場合、エラーが生成されます。
  3. ポリシーは、指定されたそれぞれの XPath（<SignedElementXPath> と <AssertionXPath>）を使用して、署名付き要素とアサーションを抽出します。これらのパスのいずれかが要素を返さない場合、エラーを発生させます。
  4. このポリシーは、アサーションが署名付き要素と同じか、署名付き要素の子であることを検証します。true でない場合、エラーを発生させます。
  5. <NotBefore> 要素または <NotOnOrAfter> 要素のいずれかがアサーションに含まれている場合、SAML コアセクション 2.5.1 に記載されているように、現在のタイムスタンプをこれらの値と照合します。
  6. このポリシーは、SAML コアセクション 2.5.1.1 に記載されている「Conditions」を処理するための追加ルールを適用します。
  7. このポリシーは、上記のトラストストア値（<TrustStore>）を使用して XML デジタル署名を検証します。検証に失敗した場合、ポリシーはエラーを発生させます。

ポリシーの処理でエラーが発生しなければ、プロキシのデベロッパーは次のことを確認できます。

  • アサーションのデジタル署名が有効で、信頼できる CA によって署名されている。
  • アサーションの有効期間内である。
  • アサーションのサブジェクトと発行者が抽出され、フロー変数に設定される。サブジェクト名の検証やターゲット システムでの検証など、これらの値を追加の認証で使用する場合は、別のポリシーを使用します。

ExtractVariables などのポリシーを使用すると、アサーションの加工前の XML を解析し、より複雑な検証を行うことができます。

フロー変数

SAML アサーションには多くの情報を指定できます。SAML アサーション自体は XML です。これは、ExtractVariables ポリシーや他のメカニズムで解析し、より複雑な検証を行うことが可能です。

変数 説明
saml.id SAML アサーションの ID
saml.issuer アサーションの「Issuer」。ネイティブの XML から文字列に変換されます。
saml.subject アサーションの「Subject」。ネイティブの XML から文字列に変換されます。
saml.valid 検証チェックの結果に応じて true または false を返します。
saml.issueInstant IssueInstant
saml.subjectFormat サブジェクトの形式
saml.scmethod サブジェクトの確認方法
saml.scdaddress サブジェクト確認データのアドレス
saml.scdinresponse レスポンスでのサブジェクト確認データ
saml.scdrcpt サブジェクト確認データの受信者
saml.authnSnooa AuthnStatement SessionNotOnOrAfter
saml.authnContextClassRef AuthnStatement AuthnContextClassRef
saml.authnInstant AuthnStatement AuthInstant
saml.authnSessionIndex AuthnStatement セッション インデックス

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、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

エラー レスポンスの例

{
  "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 ポリシー