인바운드 인증 및 승인: SAML 어설션 정책 유효성 검사
SAML 정책 유형을 사용 설정하면 API 프록시가 인바운드 SOAP 요청에 연결된 SAML 어설션 유효성을 검사할 수 있습니다. SAML 정책은 디지털 서명된 SAML 어설션이 포함된 받은 메시지의 유효성을 검사하여 잘못된 경우 거부하고 추가 정책 또는 백엔드 서비스 자체를 허용하는 변수를 설정하여 어설션 정보의 유효성을 검사합니다.
아웃바운드 토큰 생성: SAML 어설션 정책 생성
SAML 정책 유형을 사용하면 API 프록시가 SAML 어설션을 아웃바운드 XML 요청에 연결할 수 있습니다.
그런 다음 백엔드 서비스가 인증 및 승인을 위해 추가 보안 처리를 적용할 수 있도록 이러한 어설션을 사용할 수 있습니다.
이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.
정책 인스턴스의 이름입니다. 이름은 조직에서 고유해야 합니다. 이름에 사용할 수 있는 문자는 A-Z0-9._\-$
%로 제한됩니다. 그러나 Apigee UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다.
ignoreContentType 속성
true 또는 false로 설정할 수 있는 부울입니다. 메시지의 콘텐츠 유형이 XML 콘텐츠 유형이 아닌 경우 기본적으로 어설션이 생성되지 않습니다. true로 설정되면 메시지는 콘텐츠 유형과 관계없이 XML로 처리됩니다.
Issuer
ID 공급업체의 고유 식별자입니다. 선택적 ref 속성이 있는 경우 런타임 시 지정된 변수를 기준으로 발급기관의 값이 할당됩니다. 선택적 ref 속성이 없는 경우 발급기관의 값이 사용됩니다.
KeyStore
SAML 어설션에 디지털 방식으로 서명하기 위해 사용되는 비공개 키의 별칭과 비공개 키가 포함된 키 저장소의 이름입니다.
OutputVariable
FlowVariable
Message
정책의 대상입니다. 유효한 값은 message, request, response입니다. message로 설정되면 정책은 정책의 연결 지점을 기준으로 조건부로 메시지 객체를 검색합니다. 요청 흐름에 연결되면 정책은 message를 요청으로 확인하고 응답 흐름에 연결되면 정책은 message를 응답으로 확인합니다.
XPath
정책이 SAML 어설션을 연결할 아웃바운드 XML 문서의 요소를 나타내는 XPath 표현식입니다.
SignatureAlgorithm
SHA1 또는 SHA256
Subject
SAML 어설션의 주체에 대한 고유 식별자입니다. 선택적 ref 속성이 있는 경우 지정된 변수에 따라 런타임 시 Subject 값이 할당됩니다. 선택적 ref 속성이 있으면 Subject 값이 사용됩니다.
Template
있는 경우 이 템플릿을 실행하고 {} 기호로 표시된 모든 항목을 해당 변수로 대체한 다음 결과를 디지털 서명하여 어설션이 생성됩니다. 템플릿은 AssignMessage 정책 규칙에 따라 처리됩니다.
AssignMessage 정책을 참조하세요.
SAML 어설션 유효성 검사
필드 이름
설명
name 속성
정책 인스턴스의 이름입니다. 이름은 조직에서 고유해야 합니다.
이름에 사용할 수 있는 문자는 A-Z0-9._\-$ %로 제한됩니다.
그러나 Apigee UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다.
ignoreContentType 속성
true 또는 false로 설정할 수 있는 부울입니다. 메시지의 콘텐츠 유형이 XML 콘텐츠 유형이 아닌 경우 기본적으로 어설션이 생성되지 않습니다. 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
SAML 어설션에서 디지털 서명의 유효성을 검사하는 데 사용되는 신뢰할 수 있는 X.509 인증서를 포함하는 TrustStore의 이름입니다.
RemoveAssertion
true 또는 false로 설정할 수 있는 부울입니다. true인 경우 메시지가 백엔드 서비스로 전달하기 전에 SAML 어설션이 요청 메시지에서 제거됩니다.
사용 참고사항
보안 보장 마크업 언어(SAML) 사양은 애플리케이션이 인증 및 승인을 위해 XML 형식의 정보를 교환할 수 있는 형식과 프로토콜을 정의합니다.
'보안 어설션'은 앱, 앱 사용자 또는 트랜잭션의 일부 다른 참여자의 속성을 설명하는 신뢰할 수 있는 토큰입니다. 보안 어설션은 두 가지 유형의 항목에 의해 관리되고 사용됩니다.
ID 공급업체: 참여자를 대신하여 보안 어설션 생성
서비스 제공업체: ID 공급업체와 신뢰할 수 있는 관계를 통해 보안 어설션 유효성 검사
API 플랫폼은 ID 공급업체이자 서비스 제공업체 역할을 할 수 있습니다. 어설션을 생성하고 요청 메시지에 연결하여 어설션을 백엔드 서비스에서 처리하는 데 사용할 수 있도록 하여 ID 공급업체 역할을 합니다. 인바운드 요청 메시지의 어설션의 유효성을 검사하여 서비스 제공업체 역할을 합니다.
SAML 정책 유형은 SAML Core 사양 버전 2.0 및 WS-Security SAML 토큰 프로필 사양 버전 1.0과 일치하는 SAML 어설션을 지원합니다.
SAML 어설션 생성
정책 처리:
메시지가 XML이 아니며 IgnoreContentType이 true로 설정되지 않은 경우 오류가 발생합니다.
'템플릿'이 설정되어 있으면 AssignMessage 정책에 설명된 대로 템플릿을 처리합니다.
변수가 없고 IgnoreUnresolvedVariables가 설정되지 않은 경우 오류가 발생합니다.
'템플릿'이 설정되지 않은 경우 Subject 및 Issuer 매개변수의 값 또는 해당 참조를 포함하는 어설션을 구성합니다.
지정된 키를 사용하여 어설션에 서명합니다.
지정된 XPath의 메시지에 어설션을 추가합니다.
SAML 어설션 유효성 검사
정책 처리:
정책은 콘텐츠 유형이 text/(.*+)?xml 또는 application/(.*+)?xml 형식과 일치하는지 확인하여 인바운드 메시지의 유효성을 검사해 요청의 미디어 유형이 XML인지 확인합니다. 미디어 유형이 XML이 아니며 <IgnoreContentType>이 설정되지 않은 경우 정책에서 오류가 발생합니다.
정책은 XML을 파싱합니다. 파싱이 실패하면 오류가 발생합니다.
정책은 지정된 각 XPath(<SignedElementXPath> 및 <AssertionXPath>)를 사용하여 서명된 요소와 어설션을 추출합니다. 이 경로 중 하나가 요소를 반환하지 않으면 정책에서 오류가 발생합니다.
정책은 어설션이 서명된 요소와 동일하거나 서명된 요소의 하위 요소인지 확인합니다. 그렇지 않으면 정책에서 오류가 발생합니다.
<NotBefore> 또는 <NotOnOrAfter> 요소 중 하나가 어설션에 있는 경우 정책은 SAML Core 섹션 2.5.1에 설명된 대로 현재 타임스탬프를 이 값과 비교하여 확인합니다.
이 정책은 SAML Core 섹션 2.5.1.1에서 설명한 '조건' 처리를 위한 추가 규칙을 적용합니다.
정책은 위에 설명된 대로 <TrustStore> 및 <ValidateSigner> 값을 사용하여 XML 디지털 서명의 유효성을 검사합니다.
유효성 검사가 실패하면 정책에서 오류가 발생합니다.
오류가 발생하지 않고 정책이 완료되면 프록시 개발자는 다음과 같은 사항을 확실하게 확인할 수 있습니다.
어설션의 디지털 서명이 유효하며 신뢰할 수 있는 CA에서 서명했습니다.
어설션은 현재 기간 동안 유효합니다.
어설션의 주체와 발급기관이 추출되어 흐름 변수에 설정됩니다. 주체 이름이 유효한지 확인하거나 유효성 검사를 위해 대상 시스템에 전달하는 것과 같은 추가 인증에 이러한 값을 사용하는 것은 다른 정책의 책임입니다.
ExtractVariables와 같은 다른 정책은 보다 복잡한 유효성 검사를 위해 어설션의 원시 XML을 파싱할 수 있습니다.
흐름 변수
SAML 어설션에서 지정할 수 있는 많은 정보가 있습니다. SAML 어설션 자체는 더 복잡한 유효성 검사를 구현하기 위해 ExtractVariables 정책 및 다른 메커니즘을 사용하여 파싱할 수 있는 XML입니다.
변수
설명
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>).
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-05(UTC)"],[[["\u003cp\u003eThis page provides information on the SAML policy, which is applicable to both Apigee and Apigee hybrid environments.\u003c/p\u003e\n"],["\u003cp\u003eThe SAML policy enables API proxies to validate SAML assertions attached to inbound SOAP requests, ensuring message validity and enabling further security checks.\u003c/p\u003e\n"],["\u003cp\u003eThe SAML policy also allows API proxies to generate and attach SAML assertions to outbound XML requests, facilitating secure backend service interactions.\u003c/p\u003e\n"],["\u003cp\u003eThe policy supports both acting as an identity provider (generating assertions) and a service provider (validating assertions) in the context of SAML-based authentication and authorization.\u003c/p\u003e\n"],["\u003cp\u003eDeployment errors with the SAML policy are outlined, such as \u003ccode\u003eSourceNotConfigured\u003c/code\u003e, \u003ccode\u003eTrustStoreNotConfigured\u003c/code\u003e, and \u003ccode\u003eNullKeyStoreAlias\u003c/code\u003e, including their causes and detailed troubleshooting guidance.\u003c/p\u003e\n"]]],[],null,["# SAMLAssertion policies\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\n\n*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*\n\n### What\n\n- **Inbound authentication and authorization: Validate SAML Assertion\n policy** \n The SAML policy type enables API proxies to validate SAML assertions that are attached to inbound SOAP requests. The SAML policy validates incoming messages that contain a digitally-signed SAML assertion, rejects them if they are invalid, and sets variables that allow additional policies, or the backend services itself, to further validate the information in the assertion.\n- **Outbound token generation: Generate SAML Assertion policy** \n The SAML policy type enables API proxies to attach SAML assertions to outbound XML requests. Those assertions are then available to enable backend services to apply further security processing for authentication and authorization.\n\nThis policy is an *Extensible policy* and use of this policy might have cost or\nutilization implications, depending on your Apigee license. For information on policy types\nand usage implications, see\n[Policy types](/apigee/docs/api-platform/reference/policies/reference-overview-policy#policy-types).\n\n### Samples\n\n### Generate SAML assertion\n\n```vb.net\n\u003cGenerateSAMLAssertion name=\"SAML\" ignoreContentType=\"false\"\u003e\n \u003cCanonicalizationAlgorithm /\u003e\n \u003cIssuer ref=\"reference\"\u003eIssuer name\u003c/Issuer\u003e\n \u003cKeyStore\u003e\n \u003cName ref=\"reference\"\u003ekeystorename\u003c/Name\u003e\n \u003cAlias ref=\"reference\"\u003ealias\u003c/Alias\u003e\n \u003c/KeyStore\u003e\n \u003cOutputVariable\u003e\n \u003cFlowVariable\u003eassertion.content\u003c/FlowVariable\u003e\n \u003cMessage name=\"request\"\u003e\n \u003cNamespaces\u003e\n \u003cNamespace prefix=\"soap\"\u003ehttp://schemas.xmlsoap.org/soap/envelope/\u003c/Namespace\u003e\n \u003cNamespace prefix='wsse'\u003ehttp://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd\u003c/Namespace\u003e\n \u003c/Namespaces\u003e\n \u003cXPath\u003e/soap:Envelope/soap:Header/wsse:Security\u003c/XPath\u003e\n \u003c/Message\u003e\n \u003c/OutputVariable\u003e\n \u003cSignatureAlgorithm /\u003e\n \u003cSubject ref=\"reference\"\u003eSubject name\u003c/Subject\u003e\n \u003cTemplate ignoreUnresolvedVariables=\"false\"\u003e\n \u003c!-- A lot of XML goes here, within CDATA, with {} around\n each variable --\u003e\n \u003c/Template\u003e\n\u003c/GenerateSAMLAssertion\u003e\n```\n\nGenerating a SAML assertion\n\n### Validate SAML assertion\n\n```vb.net\n\u003cValidateSAMLAssertion name=\"SAML\" ignoreContentType=\"false\"\u003e\n \u003cSource name=\"request\"\u003e\n \u003cNamespaces\u003e\n \u003cNamespace prefix='soap'\u003ehttp://schemas.xmlsoap.org/soap/envelope/\u003c/Namespace\u003e\n \u003cNamespace prefix='wsse'\u003ehttp://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd\u003c/Namespace\u003e\n \u003cNamespace prefix='saml'\u003eurn:oasis:names:tc:SAML:2.0:assertion\u003c/Namespace\u003e\n \u003c/Namespaces\u003e\n \u003cAssertionXPath\u003e/soap:Envelope/soap:Header/wsse:Security/saml:Assertion\u003c/AssertionXPath\u003e\n \u003cSignedElementXPath\u003e/soap:Envelope/soap:Header/wsse:Security/saml:Assertion\u003c/SignedElementXPath\u003e\n \u003c/Source\u003e\n \u003cTrustStore\u003eTrustStoreName\u003c/TrustStore\u003e\n \u003cRemoveAssertion\u003efalse\u003c/RemoveAssertion\u003e\n\u003c/ValidateSAMLAssertion\u003e\n```\n\nValidating a SAML assertion\n\n*** ** * ** ***\n\nElement reference\n-----------------\n\n### Generate SAML Assertion\n\n### Validate SAML Assertion\n\n*** ** * ** ***\n\nUsage notes\n-----------\n\nThe Security Assertion Markup Language (SAML) specification defines formats and protocols that\nenable applications to exchange XML-formatted information for authentication and\nauthorization.\n\nA \"security assertion\" is a trusted token that describes an attribute of an app, an app user,\nor some other participant in a transaction. Security assertions are managed and consumed by two\ntypes of entities:\n\n- Identity providers: Generate security assertions on behalf of participants\n- Service providers: Validate security assertions through trusted relationships with identity providers\n\nThe API platform can act as an identity provider and as a service provider. It acts as an\nidentity provider by generating assertions and attaching them to request messages, making those\nassertions available for processing by backend services. It acts as a service provider by\nvalidating assertions on inbound request messages.\n\nThe SAML policy type supports SAML assertions that match version 2.0 of the SAML Core\nSpecification and Version 1.0 of the WS-Security SAML Token Profile specification.\n\n### Generate SAML Assertion\n\nPolicy processing:\n\n1. If the message is not XML, and IgnoreContentType is not set to `true`, then raise a fault.\n2. If \"Template\" is set, then process the template as described for the AssignMessage policy. If any variables are missing and IgnoreUnresolvedVariables is not set, then raise a fault.\n3. If \"Template\" is not set, then construct an assertion that includes the values of the Subject and Issuer parameters or their references.\n4. Sign the assertion using the specified key.\n5. Add the assertion to the message at the specified XPath.\n\n### Validate SAML Assertion\n\nPolicy processing:\n\n1. The policy checks the inbound message to verify that the request's media type is XML, by checking if the content type matches the formats `text/(.*+)?xml` or `application/(.*+)?xml`. If the media type is not XML and `\u003cIgnoreContentType\u003e` is not set, then the policy will raise a fault.\n2. The policy will parse the XML. If parsing fails then it will raise a fault.\n3. The policy will extract the signed element and the assertion, using the respective XPaths specified (`\u003cSignedElementXPath\u003e` and `\u003cAssertionXPath\u003e`). If either of these paths do not return an element, then the policy will raise a fault.\n4. The policy will verify that the Assertion is the same as the signed element, or is a child of the signed element. If this is not true, then the policy will raise a fault.\n5. If either of the `\u003cNotBefore\u003e` or `\u003cNotOnOrAfter\u003e` elements are present in the assertion, the policy will check the current timestamp against these values, as described in SAML Core section 2.5.1.\n6. The policy will apply any additional rules for processing the \"Conditions\" as described in SAML Core section 2.5.1.1.\n7. The policy will validate the XML digital signature, using the values of `\u003cTrustStore\u003e` and `\u003cValidateSigner\u003e` as described above. If validation fails, then the policy will raise a fault.\n\nOnce the policy has completed without raising a fault, the developer of the proxy can be sure\nof the following:\n\n- The digital signature on the assertion is valid and was signed by a trusted CA\n- The assertion is valid for the current time period\n- The subject and issuer of the assertion will be extracted and set in flow variables. It is the responsibility of other policies to use these values for additional authentication, such as checking that the subject name is valid, or passing it to a target system for validation.\n\nOther policies, such as ExtractVariables, may be used to parse the raw XML of the assertion\nfor more complex validation.\n\n*** ** * ** ***\n\nFlow variables\n--------------\n\nThere are many pieces of information that may be specified in a SAML assertion. The SAML\nassertion itself is XML that can be parsed using the [ExtractVariables policy](/apigee/docs/api-platform/reference/policies/extract-variables-policy) and other\nmechanisms in order to implement more complex validations.\n\nError reference\n---------------\n\n\nThis section describes the fault codes and error messages that are returned\nand fault variables that are set by Apigee when this policy triggers an error.\nThis information is important to know if you are developing fault rules to\nhandle faults. To learn more, see [What you need to know\nabout policy errors](/apigee/docs/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling\nfaults](/apigee/docs/api-platform/fundamentals/fault-handling).\n\n### Deployment errors\n\nThese errors can occur when you deploy a proxy containing this policy.\n| **Tip:** Need help resolving an error? Click *build* in the Fix column for detailed troubleshooting information.\n\n### Fault variables\n\nThese variables are set when a runtime error occurs. For more information, see [What you need to know\nabout policy errors](/apigee/docs/api-platform/fundamentals/what-you-need-know-about-policy-errors).\n\n### Example error response\n\n**Note:** For error handling, the best practice is to trap the `errorcode` part of the error response. Do not rely on the text in the `faultstring`, because it could change. \n\n```transact-sql\n{\n \"fault\": {\n \"faultstring\": \"GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type\",\n \"detail\": {\n \"errorcode\": \"steps.saml.generate.InvalidMediaTpe\"\n }\n }\n}\n```\n\n### Example fault rule\n\n```scdoc\n\u003cFaultRules\u003e\n \u003cFaultRule name=\"invalid_saml_rule\"\u003e\n \u003cStep\u003e\n \u003cName\u003einvalid-saml\u003c/Name\u003e\n \u003c/Step\u003e\n \u003cCondition\u003e(GenerateSAMLAssertion.failed = \"true\")\u003c/Condition\u003e\n \u003c/FaultRule\u003e\n\u003c/FaultRules\u003e\n```\n\n\u003cbr /\u003e\n\nRelated topics\n--------------\n\nExtracting variables: [Extract Variables\npolicy](/apigee/docs/api-platform/reference/policies/extract-variables-policy)"]]
