SAMLAssertion ポリシー

このページの内容は ApigeeApigee ハイブリッドに該当します。

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

ポリシー アイコン

内容

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

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

サンプル

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

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>
    <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 アサーションの検証


要素リファレンス

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

フィールド名 説明
name 属性 ポリシー インスタンスの名前。名前は、組織内で一意にする必要があります。名前に使用できる文字は A-Z0-9._\-$ % のみです。ただし、Apigee 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 属性が存在する場合、Subject の値は指定された変数に基づいてランタイムに割り当てられます。オプションの ref 属性が存在する場合は、Subject の値が使用されます。
Template
存在する場合は、このテンプレートを実行し、{} で示されるすべてを対応する変数に置き換えて、結果にデジタル署名して、アサーションを生成します。テンプレートは AssignMessage ポリシールールの後に処理されます。Assign Message ポリシーをご覧ください。

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

フィールド名 説明
name 属性
ポリシー インスタンスの名前。名前は、組織内で一意にする必要があります。名前に使用できる文字は A-Z0-9._\-$ % のみです。ただし、Apigee UI には、英数字以外の文字は自動的に削除されるなどの追加の制限があります。
ignoreContentType 属性 true または false に設定できるブール値。デフォルトでは、メッセージのコンテンツ タイプが XML Content-Type でない場合、アサーションは生成されません。これが true に設定されている場合、メッセージはコンテンツ タイプに関係なく XML として扱われます。
Source ポリシーのターゲット。有効な値は messagerequestresponse です。message に設定すると、ポリシーはポリシーの接続ポイントに基づいて条件付きでメッセージ オブジェクトを取得します。リクエスト フローに接続すると、ポリシーは messagerequest に解決し、レスポンス フローに接続すると、messageresponse に解決します。
XPath
非推奨Source の子。AssertionXPathSignedElementXPath を使用します。
AssertionXPath
Source の子。ポリシーが SAML アサーションを抽出するインバウンド XML ドキュメントの要素を表す XPath 式。
SignedElementXPath
Source の子。ポリシーが署名付き要素を抽出できるインバウンド XML ドキュメントの要素を示す XPath 式。これは、AssertionXPath の 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. 指定されたそれぞれの XPath(<SignedElementXPath><AssertionXPath>)を使用して、署名付き要素とアサーションを抽出します。これらのパスのいずれかが要素を返さない場合、エラーが生成されます。
  4. アサーションが署名付き要素と同じか、署名付き要素の子であることを検証します。true でない場合、エラーを発生させます。
  5. <NotBefore> 要素または <NotOnOrAfter> 要素がアサーションに含まれている場合、SAML コアセクション 2.5.1 に記載されているように、現在のタイムスタンプをこれらの値と照合します。
  6. SAML コアセクション 2.5.1.1 に記載されている「Conditions」を処理するための追加ルールを適用します。
  7. 上記の <TrustStore><ValidateSigner> の値を使用して 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 ポリシー