SAMLAssertion ポリシー

概要

• 受信認証と認可: SAML Assertion ポリシーの検証
  SAML ポリシータイプを使うと、API プロキシは、内向きの SOAP リクエストに追加された SAML アサーションを検証できます。SAML ポリシーは、デジタル署名された SAML アサーションの入った受信メッセージを検証し、無効な場合は拒否し、他のポリシーまたはバックエンド サービス自体がアサーションの情報をさらに検証できるように変数を設定します。
• 送信トークンの生成: SAML Assertion ポリシーの生成
  SAML ポリシーを使用すると、API プロキシで SAML アサーションを送信 XML リクエストに追加できます。これらのアサーションを使用すると、認証と認可用の追加のセキュリティ処理をバックエンド サービスに適用できます。

サンプル

<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="test">http://www.example.com/test</Namespace>
      </Namespaces>
      <XPath>/envelope/header</XPath>
    </Message>
  </OutputVariable>
  <SignatureAlgorithm />
  <Subject ref="reference">Subject name</Subject>
  <Template ignoreUnresolvedVariables="false">
    <!-- A lot of XML goes here, in CDATA, with {} around
         each variable -->
  </Template>
</GenerateSAMLAssertion>

<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>
    <XPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</XPath>
  </Source>
  <TrustStore>TrustStoreName</TrustStore>
  <RemoveAssertion>false</RemoveAssertion>
</ValidateSAMLAssertion>

要素リファレンス

SAML アサーションを生成する

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

使用上の注意

SAML（Security Assertion Markup Language）は、アプリケーション間で認証と認可に使用する情報を XML 形式で交換するためのデータ形式とプロトコルを定義しています。

「セキュリティ アサーション」は、アプリ、アプリのユーザー、トランザクションの他の参加者の属性を表す信頼できるトークンです。セキュリティ アサーションは、次の 2 種類のエンティティによって管理されます。

• ID プロバイダ: 参加者の代わりにセキュリティ アサーションを生成します。
• サービス プロバイダ: ID プロバイダとの信頼関係により、セキュリティ アサーションを検証します。

API Platform は、ID プロバイダまたはサービス プロバイダとして機能します。ID プロバイダとしては、アサーションを生成してリクエスト メッセージに追加し、バックエンド サービスで処理できるようにします。サービス プロバイダとしては、受信リクエスト メッセージのアサーションを検証します。

SAML ポリシータイプは、SAML コア仕様のバージョン 2.0 と WS-Security SAML Token Profile 仕様のバージョン 1.0 に準拠している SAML アサーションをサポートします。

SAML アサーションを生成する

ポリシーの処理:

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

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

ポリシーの処理:

1. 受信メッセージを確認し、コンテンツ タイプが text/(.*+)?xml または application/(.*+)?xml と一致する場合、リクエストのメディアタイプが XML であることを確認します。メディアタイプが XML でない場合、または「IgnoreContentType」が設定されていない場合、エラーを発生させます。
2. XML を解析します。解析に失敗した場合、エラーを発生させます。
3. 上記の TrustStore と ValidateSigner の値を使用して、XML のデジタル署名を検証します。検証に失敗した場合、エラーを発生させます。
4. 現在のタイムスタンプ（存在する場合）をアサーションの NotBefore 要素や NotOnOrAfter 要素と比較します（SAML コア仕様、第 2.5.1 項を参照）。
5. 「Conditions」を処理する追加ルールを実行します（SAML コア仕様、第 2.5.1.1 項を参照）。

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

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

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

フロー変数

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

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Example fault rule

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

関連トピック

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