ValidateSAMLAssertion 정책

확장 가능한 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

ValidateSAMLAssertion 정책을 사용 설정하면 API 프록시가 인바운드 SOAP 요청에 연결된 SAML 어설션 유효성을 검사할 수 있습니다. SAML 정책은 디지털 서명된 SAML 어설션이 포함된 받은 메시지의 유효성을 검사하여 잘못된 경우 거부하고 추가 정책 또는 백엔드 서비스 자체를 허용하는 변수를 설정하여 어설션 정보의 유효성을 검사합니다. 자세한 내용은 SAML 정책 개요를 참고하세요.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참고하세요.

샘플

<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 어설션 유효성 검사

필드 이름 설명
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 어설션이 요청 메시지에서 제거됩니다.

사용 참고사항

정책 처리:

  1. 정책은 콘텐츠 유형이 text/(.*+)?xml 또는 application/(.*+)?xml 형식과 일치하는지 확인하여 인바운드 메시지의 유효성을 검사해 요청의 미디어 유형이 XML인지 확인합니다. 미디어 유형이 XML이 아니며 ignoreContentType 속성이 true로 설정되지 않은 경우 정책에서 오류가 발생합니다.
  2. 정책은 XML을 파싱합니다. 파싱이 실패하면 오류가 발생합니다.
  3. 정책은 지정된 각 XPath(<SignedElementXPath> 및 <AssertionXPath>)를 사용하여 서명된 요소와 어설션을 추출합니다. 이 경로 중 하나가 요소를 반환하지 않으면 정책에서 오류가 발생합니다.
  4. 정책은 어설션이 서명된 요소와 동일하거나 서명된 요소의 하위 요소인지 확인합니다. 그렇지 않으면 정책에서 오류가 발생합니다.
  5. <NotBefore> 또는 <NotOnOrAfter> 요소 중 하나가 어설션에 있는 경우 정책은 SAML Core 섹션 2.5.1에 설명된 대로 현재 타임스탬프를 이 값과 비교하여 확인합니다.
  6. 이 정책은 SAML Core 섹션 2.5.1.1에서 설명한 '조건' 처리를 위한 추가 규칙을 적용합니다.
  7. 정책은 위에 설명된 신뢰 저장소 값 (<TrustStore>)을 사용하여 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>).
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 어설션 정책 구성을 검증하기 위한 오류 프리픽스는 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>

관련 주제

변수 추출: 변수 추출 정책