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 ポリシーや他のメカニズムで解析し、より複雑な検証を行うことが可能です。

エラー リファレンス

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

デプロイエラー

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

障害変数

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

エラー レスポンスの例

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