SAMLAssertion ポリシー

概要

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

サンプル

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

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

SAML アサーションの生成

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

<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 アサーションを生成する

フィールド名 説明
name 属性 ポリシー インスタンスの名前。名前は、組織内で一意にする必要があります。名前に使用できる文字は A-Z0-9._\-$ % のみです。ただし、管理 UI では、英数字以外の文字を自動的に削除するなど、追加の制限が適用されます。
ignoreContentType 属性 true または false に設定できるブール値。デフォルトでは、メッセージのコンテンツ タイプが XML Content-Type でない場合、アサーションは生成されません。これが true に設定されている場合、メッセージはコンテンツ タイプに関係なく XML として扱われます。
Issuer
ID プロバイダの一意の識別子。オプションの ref 属性が存在する場合は、指定された変数に基づいて発行者の値がランタム時に割り当てられます。オプションの ref 属性が存在しない場合は、発行者の値が使用されます。
KeyStore
SAML アサーションのデジタル署名に使用する秘密鍵とそのエイリアスを含む KeyStore の名前。
OutputVariable
FlowVariable
Message ポリシーのターゲット。有効な値は messagerequestresponse です。message に設定すると、ポリシーはポリシーの接続ポイントに基づいて条件付きでメッセージ オブジェクトを取得します。リクエスト フローに接続すると、ポリシーは message をリクエストに解決し、レスポンス フローに接続すると、message をレスポンスに解決します。
XPath ポリシーが SAML アサーションを追加する送信 XML ドキュメントの要素を表す XPath 式。
SignatureAlgorithm SHA1 または SHA256
Subject
SAML アサーションのサブジェクトの一意の識別子。オプションの ref 属性が存在する場合、件名の値は指定された変数に基づいてランタイム時に割り当てられます。オプションの ref 属性が存在する場合、件名の値が使用されます。
Template
存在する場合は、このテンプレートを実行し、{} で示されるすべてを対応する変数に置き換えて、結果にデジタル署名します。テンプレートは AssignMessage ポリシールールの後に処理されます。 Assign Message ポリシーをご覧ください。

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

フィールド名 説明
name 属性
ポリシー インスタンスの名前。名前は、組織内で一意にする必要があります。 名前に使用できる文字は A-Z0-9._\-$ % のみです。 ただし、管理 UI では、英数字以外の文字を自動的に削除するなど、追加の制限が適用されます。
ignoreContentType 属性 true または false に設定できるブール値。デフォルトでは、メッセージのコンテンツ タイプが XML Content-Type でない場合、アサーションは生成されません。これが true に設定されている場合、メッセージはコンテンツ タイプに関係なく XML として扱われます。
Source ポリシーのターゲット。有効な値は messagerequestresponse です。message に設定すると、ポリシーはポリシーの接続ポイントに基づいて条件付きでメッセージ オブジェクトを取得します。リクエスト フローに接続すると、ポリシーは message をリクエストに解決し、レスポンス フローに接続すると、message をレスポンスに解決します。
XPath
Source の子。ポリシーが SAML アサーションを抽出する受信 XML ドキュメントの要素を表す XPath 式。
TrustStore
信頼された X.509 証明書を含むトラストストアの名前。この証明書は、SAML アサーションのデジタル署名の検証に使用されます。
RemoveAssertion
true または false に設定できるブール値。true の場合、メッセージがバックエンド サービスに転送される前に、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 ポリシーや他のメカニズムで解析し、より複雑な検証を行うことが可能です。

変数 説明
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 セッション インデックス

エラー リファレンス

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

デプロイエラー

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

エラー名 原因 解決方法
SourceNotConfigured Validate SAML Assertion ポリシーで <Source><XPath><Namespaces><Namespace> の要素の 1 つ以上が定義されていないか、空になっています。
TrustStoreNotConfigured <TrustStore> 要素が空である、または ValidateSAMLAssertion ポリシーで指定されていない場合、API プロキシのデプロイは失敗します。有効なトラストストアが必要です。
NullKeyStoreAlias 子要素 <Alias> が空である、または Generate SAML Assertion ポリシーの <Keystore> 要素で指定されていない場合、API プロキシのデプロイは失敗します。有効なキーストア エイリアスが必要です。
NullKeyStore 子要素 <Name> が空か、GenerateSAMLAssertion ポリシーの <Keystore> 要素で指定されていない場合、API プロキシのデプロイが失敗します。有効なキーストア名が必要です。
NullIssuer <Issuer> 要素が空である、または Generate SAML Assertion ポリシーで指定されていない場合、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 ポリシー