GenerateSAMLAssertion 정책

확장 가능한 정책

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

GenerateSAMLAssertion 정책을 사용하면 API 프록시가 SAML 어설션을 아웃바운드 XML 요청에 연결할 수 있습니다. 그런 다음 백엔드 서비스가 인증 및 승인을 위해 추가 보안 처리를 적용할 수 있도록 이러한 어설션을 사용할 수 있습니다. 자세한 내용은 SAML 정책 개요를 참고하세요.

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

샘플

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

요소 참조

이 섹션에는 GenerateSAMLAssertion 정책의 요소와 속성이 나열되어 있습니다.

최상위 요소에 적용되는 속성

<GenerateSAMLAssertion name="SAML-A1" continueOnError="false" enabled="true" async="false">

다음 속성은 모든 정책 상위 요소에 공통적으로 적용됩니다.

속성	설명	기본값	존재 여부
이름	정책의 내부 이름입니다. 이름에 사용할 수 있는 문자는 `A-Z0-9._\-$ %`로 제한됩니다. 그러나 Apigee UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다. 선택적으로 `<displayname></displayname>` 요소를 사용하여 Apigee UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.	해당 사항 없음	필수
사용 설정됨	정책을 시행하려면 `true`로 설정합니다. `false`로 설정하여 정책을 '사용 중지'합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	참	선택사항

SAML 어설션 생성을 위한 요소 및 속성

필드 이름	설명
`ignoreContentType` 속성	`true` 또는 `false`로 설정할 수 있는 부울입니다. 메시지의 콘텐츠 유형이 XML 콘텐츠 유형이 아닌 경우 기본적으로 어설션이 생성되지 않습니다. `true`로 설정되면 메시지는 콘텐츠 유형과 관계없이 XML로 처리됩니다.
`Issuer`	ID 공급업체의 고유 식별자입니다. 선택적 `ref` 속성이 있는 경우 런타임 시 지정된 변수를 기준으로 발급기관의 값이 할당됩니다. 선택적 `ref` 속성이 없는 경우 발급기관의 값이 사용됩니다.
`KeyStore`	SAML 어설션에 디지털 방식으로 서명하기 위해 사용되는 비공개 키의 별칭과 비공개 키가 포함된 키 저장소의 이름입니다.
`OutputVariable`	생성된 SAML 어설션이 배치될 위치를 지정합니다. 어설션은 흐름 변수에 저장하거나 기존 메시지에 삽입할 수 있습니다.
`FlowVariable`	생성된 SAML 어설션 콘텐츠가 저장될 흐름 변수의 이름을 지정합니다. 이는 `<Message>` 요소를 사용하여 기존 XML 메시지에 어설션 을 삽입하는 대신 사용할 수 있습니다.
`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`인 경우에만 지원됩니다.

사용 참고사항

정책 처리:

메시지가 XML이 아니며 ignoreContentType이 true로 설정되지 않은 경우 오류가 발생합니다.
Template이 설정되어 있으면 AssignMessage 정책에 설명된 대로 템플릿을 처리합니다. 변수가 없고 ignoreUnresolvedVariables가 설정되지 않은 경우 오류가 발생합니다.
Template이 설정되지 않은 경우 Subject 및 Issuer 매개변수의 값 또는 해당 참조를 포함하는 어설션을 구성합니다.
지정된 키를 사용하여 어설션에 서명합니다.
지정된 XPath의 메시지에 어설션을 추가합니다.

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 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>