SAMLAssertion ポリシー

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

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`	ポリシーのターゲット。有効な値は `message`、`request`、`response` です。`message` に設定すると、ポリシーはポリシーの接続ポイントに基づいて条件付きでメッセージオブジェクトを取得します。リクエストフローに接続すると、ポリシーは `message` をリクエストに解決し、レスポンスフローに接続すると、`message` をレスポンスに解決します。
`XPath`	ポリシーが SAML アサーションを追加するアウトバウンド XML ドキュメントの要素を表す XPath 式。
`SignatureAlgorithm`	SHA1 または SHA256
`Subject`	SAML アサーションのサブジェクトの一意の識別子。オプションの `ref` 属性が存在する場合、Subject の値は指定された変数に基づいてランタイムに割り当てられます。オプションの `ref` 属性が存在する場合は、Subject の値が使用されます。
`Template`	存在する場合は、このテンプレートを実行し、`{}` で示されるすべてを対応する変数に置き換えて、結果にデジタル署名します。テンプレートは AssignMessage ポリシールールの後に処理されます。Assign Message ポリシーをご覧ください。 `<Template>` 要素は、メッセージテンプレートという動的文字列置換機能をサポートしています。メッセージテンプレートは、ポリシーの署名が `GenerateSamlAssertion` の場合にのみサポートされます。

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 アサーションがリクエストメッセージから削除されます。

使用上の注意

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

ポリシーの処理:

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

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

ポリシーの処理:

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

エラーレスポンスの例

注: ベストプラクティスとして、エラー処理でエラーレスポンスの errorcode の部分をトラップすることをおすすめします。faultstring のテキストには依存しないでください。この部分は変更される可能性があります。

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

SAMLAssertion ポリシー

内容

サンプル

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

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

要素リファレンス

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

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

使用上の注意

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

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

フロー変数

エラー リファレンス

デプロイエラー

障害変数

エラー レスポンスの例

障害ルールの例

関連トピック

エラーリファレンス

エラーレスポンスの例