SAMLAssertion 정책

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

대상

인바운드 인증 및 승인: SAML 어설션 정책 유효성 검사
SAML 정책 유형을 사용 설정하면 API 프록시가 인바운드 SOAP 요청에 연결된 SAML 어설션 유효성을 검사할 수 있습니다. SAML 정책은 디지털 서명된 SAML 어설션이 포함된 받은 메시지의 유효성을 검사하여 잘못된 경우 거부하고 추가 정책 또는 백엔드 서비스 자체를 허용하는 변수를 설정하여 어설션 정보의 유효성을 검사합니다.
아웃바운드 토큰 생성: SAML 어설션 정책 생성
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 콘텐츠 유형이 아닌 경우 기본적으로 어설션이 생성되지 않습니다. `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 정책을 참조하세요. `<Template>` 요소는 메시지 템플릿이라는 동적 문자열 대체 기능을 지원합니다. 메시지 템플릿은 정책 서명이 `GenerateSamlAssertion`인 경우에만 지원됩니다.

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>`).
`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`

오류 응답 예시

참고: 오류 처리에서 권장사항은 오류 응답의 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 어설션 유효성 검사

흐름 변수

오류 참조

배포 오류

오류 변수

오류 응답 예시

오류 규칙 예시

관련 주제