Políticas de declaração SAML

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

O que

Autenticação e autorização de entrada: valide a política de asserção SAML
O tipo de política SAML permite que os proxies de API validem declarações SAML anexadas a solicitações SOAP de entrada. A política SAML valida mensagens recebidas que contêm uma declaração SAML assinada digitalmente, rejeita-as se forem inválidas e definem variáveis que permitem políticas adicionais ou os próprios serviços de back-end para validar ainda mais as informações na declaração.
Geração de token de saída: gerar política de declaração de SAML
O tipo de política SAML permite que os proxies de API anexem declarações SAML às solicitações XML de saída. Essas declarações estão disponíveis para permitir que os serviços de back-end apliquem mais processamento de segurança para autenticação e autorização.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Amostras

Gerar declaração 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>

Como gerar uma declaração SAML

Validar declaração 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>

Como validar uma declaração SAML

Referência de elemento

Gerar declaração SAML

Nome do campo	Descrição
Atributo `name`	O nome da instância da política. Ele precisa ser exclusivo na organização. Os caracteres que podem ser usados no nome são restritos a: `A-Z0-9._\-$ %`. No entanto, a IU da Apigee impõe outras restrições, como a remoção automática de caracteres que não são alfanuméricos.
Atributo `ignoreContentType`	Um booleano que pode ser definido como `true` ou `false`. Por padrão, a declaração não será gerada se o tipo de conteúdo da mensagem não for um tipo de conteúdo XML. Se for definido como `true`, a mensagem será tratada como XML independentemente do tipo de conteúdo.
`Issuer`	O identificador exclusivo do provedor de identidade. Se o atributo opcional `ref` estiver presente, o valor do emissor será atribuído no ambiente de execução com base na variável especificada. Se o atributo `ref` opcional não estiver presente, o valor de Emissor será usado.
`KeyStore`	O nome do keystore que contém a chave privada e o alias da chave privada usada para assinar digitalmente as declarações SAML.
`OutputVariable`
`FlowVariable`
`Message`	O destino da política. Os valores válidos são `message`, `request` e `response`. Quando definida como `message`, a política recupera condicionalmente o objeto de mensagem com base no ponto de anexo da política. Quando anexada ao fluxo de solicitação, a política resolve `message` para solicitar e, quando anexada ao fluxo de resposta, a política resolve `message` para responder.
`XPath`	Uma expressão XPath que indica o elemento no documento XML de saída ao qual a política anexará a declaração SAML.
`SignatureAlgorithm`	SHA1 ou SHA256
`Subject`	Identificador exclusivo do assunto da declaração SAML. Se o atributo `ref` opcional estiver presente, o valor de Assunto será atribuído no ambiente de execução com base na variável especificada. Se o atributo opcional `ref` estiver presente, o valor do Assunto será usado.
`Template`	Se presente, a declaração será gerada executando este modelo, substituindo tudo indicado por `{}` pela variável correspondente e, em seguida, assinando o resultado digital. O modelo é processado seguindo as regras da política AssignMessage. Consulte Política AssignMessage. O elemento `<Template>` é compatível com o recurso de substituição de strings dinâmicas chamado modelo de mensagem. O modelo de mensagens só é compatível quando a assinatura da política é `GenerateSamlAssertion`.

Validar declaração SAML

Nome do campo	Descrição
Atributo `name`	O nome da instância da política. Ele precisa ser exclusivo na organização. Os caracteres que podem ser usados no nome são restritos a: `A-Z0-9._\-$ %`. No entanto, a IU da Apigee impõe outras restrições, como a remoção automática de caracteres que não são alfanuméricos.
Atributo `ignoreContentType`	Um booleano que pode ser definido como `true` ou `false`. Por padrão, a declaração não será gerada se o tipo de conteúdo da mensagem não for um tipo de conteúdo XML. Se for definido como `true`, a mensagem será tratada como XML independentemente do tipo de conteúdo.
`Source`	O destino da política. Os valores válidos são `message`, `request` e `response`. Quando definida como `message`, a política recupera condicionalmente o objeto de mensagem com base no ponto de anexo da política. Quando anexada ao fluxo de solicitação, a política resolve `message` para `request` e, quando anexada ao fluxo de resposta, a política resolve `message` para `response`.
`XPath`	Obsoleto. Filho de `Source`. Usar `AssertionXPath` e `SignedElementXPath`.
`AssertionXPath`	Filho de `Source`. Uma expressão XPath que indica o elemento no documento XML de entrada a partir do qual a política pode extrair a declaração SAML.
`SignedElementXPath`	Filho de `Source`. Uma expressão XPath que indica o elemento no documento XML de entrada a partir do qual a política pode extrair o elemento assinado. Pode ser diferente ou igual ao XPath de `AssertionXPath`.
`TrustStore`	O nome do TrustStore que contém certificados X.509 confiáveis usados para validar assinaturas digitais em declarações de SAML.
`RemoveAssertion`	Um booleano que pode ser definido como `true` ou `false`. Quando `true`, a declaração SAML será removida da mensagem de solicitação antes que a mensagem seja encaminhada para o serviço de back-end.

Observações sobre uso

A especificação da Linguagem de marcação para autorização de segurança (SAML, na sigla em inglês) define formatos e protocolos que permitem aos aplicativos trocar informações formatadas como XML para autenticação e autorização.

Uma "declaração de segurança" é um token confiável que descreve um atributo de um app, um usuário do app ou algum outro participante em uma transação. As declarações de segurança são gerenciadas e consumidas por dois tipos de entidades:

Provedores de identidade: gerar declarações de segurança em nome dos participantes
Provedores de serviços: valide declarações de segurança por meio de relações confiáveis com provedores de identidade

A plataforma de API pode atuar como um provedor de identidade e como um provedor de serviços. Ele atua como um provedor de identidade gerando declarações e anexando-as para solicitar mensagens, disponibilizando-as para processamento por serviços de back-end. Ele atua como um provedor de serviços validando declarações em mensagens de solicitação de entrada.

O tipo de política SAML é compatível com declarações SAML que correspondem à versão 2.0 da Especificação SAML Core e à versão 1.0 da especificação WS-Security SAML Token Profile.

Gerar declaração SAML

Processamento de políticas:

Se a mensagem não for XML e IgnoreContentType não estiver definido como true, uma falha será gerada.
Se "Modelo" estiver definido, processe o modelo conforme descrito para a política do AssignMessage. Se faltar variáveis e IgnoreUnresolvedVariables não estiver definido, será gerada uma falha.
Se "Modelo" não estiver definido, crie uma declaração que inclua os valores dos parâmetros Assunto e Emissor ou as referências deles.
Assine a declaração usando a chave especificada.
Adicione a declaração à mensagem no XPath especificado.

Validar declaração SAML

Processamento de políticas:

A política verifica a mensagem recebida para verificar se o tipo de mídia da solicitação é XML, verificando se o tipo de conteúdo corresponde aos formatos text/(.*+)?xml ou application/(.*+)?xml. Se o tipo de mídia não for XML e <IgnoreContentType> não estiver definido, a política gerará uma falha.
A política analisará o XML. Se a análise falhar, uma falha será gerada.
A política extrairá o elemento assinado e a declaração, usando os respectivos XPaths especificados (<SignedElementXPath> e <AssertionXPath>). Se um desses caminhos não retornar um elemento, a política gerará uma falha.
A política verificará se a declaração é igual ao elemento assinado ou é um filho do elemento assinado. Se isso não for verdade, a política emitirá uma falha.
Se um dos elementos <NotBefore> ou <NotOnOrAfter> estiver presente na declaração, a política verificará o carimbo de data/hora atual em relação a esses valores, conforme descrito na seção 2.5.1 do núcleo SAML.
A política aplicará outras regras para processar as "Condições", conforme descrito na seção 2.5.1.1 do núcleo SAML.
A política validará a assinatura digital XML, usando os valores de <TrustStore> e <ValidateSigner>, conforme descrito acima. Se a validação falhar, a política emitirá uma falha.

Quando a política for concluída sem gerar uma falha, o desenvolvedor do proxy poderá garantir o seguinte:

A assinatura digital na declaração é válida e foi assinada por uma CA confiável.
A declaração é válida para o período atual.
O assunto e o emissor da declaração serão extraídos e definidos em variáveis de fluxo. É responsabilidade de outras políticas usar esses valores para autenticação adicional, como verificar se o nome do assunto é válido ou passá-lo para um sistema de destino para validação.

Outras políticas, como ExtractVariables, podem ser usadas para analisar o XML bruto da declaração para uma validação mais complexa.

Variáveis de fluxo

Há muitas informações que podem ser especificadas em uma declaração SAML. A própria declaração SAML é XML, que pode ser analisada com a política ExtractVariables e outros mecanismos para implementar validações mais complexas.

Variável	Descrição
`saml.id`	O ID da declaração SAML
`saml.issuer`	O "Emissor" da declaração, convertido do tipo XML nativo para uma string
`saml.subject`	O "Assunto" da declaração, convertido do tipo XML nativo em uma string
`saml.valid`	Retorna verdadeiro ou falso com base no resultado da verificação de validade
`saml.issueInstant`	IssueInstant
`saml.subjectFormat`	Formato do assunto
`saml.scmethod`	Método de confirmação do assunto
`saml.scdaddress`	Endereço dos dados para confirmação do assunto
`saml.scdinresponse`	Dados de confirmação do assunto em resposta
`saml.scdrcpt`	Destinatário dos dados de confirmação do assunto
`saml.authnSnooa`	AuthnStatement SessionNotOnOrAfter
`saml.authnContextClassRef`	AuthnStatement AuthnContextClassRef
`saml.authnInstant`	AuthnStatement AuthInstant
`saml.authnSessionIndex`	Índice de sessão do AuthnStatement

Referência de erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`SourceNotConfigured`	One or more of the following elements of the `ValidateSAMLAssertion` policy is not defined or empty: `<Source>`, `<XPath>`, `<Namespaces>`, `<Namespace>`.
`TrustStoreNotConfigured`	If the `<TrustStore>` element is empty or not specified in the `ValidateSAMLAssertion` policy, then the deployment of the API proxy fails. A valid truststore is required.
`NullKeyStoreAlias`	If the child element `<Alias>` is empty or not specified in the `<Keystore>` element of `GenerateSAMLAssertion` policy, then the deployment of the API proxy fails. A valid keystore alias is required.
`NullKeyStore`	If the child element `<Name>` is empty or not specified in the `<Keystore>` element of `GenerateSAMLAssertion` policy, then the deployment of the API proxy fails. A valid keystore name is required.
`NullIssuer`	If the `<Issuer>` element is empty or not specified in the `GenerateSAMLAssertion` policy, then the deployment of the API proxy fails. A valid `<Issuer>` value is required.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault. The fault name is the last part of the fault code.	`fault.name = "InvalidMediaTpe"`
`GenerateSAMLAssertion.failed`	For a validate SAML assertion policy configuration, the error prefix is `ValidateSAMLAssertion`.	`GenerateSAMLAssertion.failed = true`

Example error response

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.

{
  "fault": {
    "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type",
    "detail": {
      "errorcode": "steps.saml.generate.InvalidMediaTpe"
    }
  }
}

Example fault rule

<FaultRules>
    <FaultRule name="invalid_saml_rule">
        <Step>
            <Name>invalid-saml</Name>
        </Step>
        <Condition>(GenerateSAMLAssertion.failed = "true")</Condition>
    </FaultRule>
</FaultRules>

Temas relacionados

Como extrair variáveis: Política de extração de variáveis