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

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Nome do erro	Causa	Correção
`SourceNotConfigured`	Um ou mais dos seguintes elementos da política `ValidateSAMLAssertion` não está definido ou está vazio: `<Source>`, `<XPath>`, `<Namespaces>`, `<Namespace>`.
`TrustStoreNotConfigured`	Se o elemento `<TrustStore>` estiver vazio ou não for especificado na política `ValidateSAMLAssertion`, a implantação do proxy de API falhará. Uma truststore válido é obrigatório.
`NullKeyStoreAlias`	Se o elemento filho `<Alias>` estiver vazio ou não especificado no elemento `<Keystore>` da política `GenerateSAMLAssertion`, a implantação do proxy de API falhará. Um alias de keystore válido é obrigatório.
`NullKeyStore`	Se o elemento filho `<Name>` estiver vazio ou não especificado no elemento `<Keystore>` da política `GenerateSAMLAssertion`, a implantação do proxy de API falhará. Um nome válido de keystore é obrigatório.
`NullIssuer`	Se o elemento `<Issuer>` estiver vazio ou não for especificado na política `GenerateSAMLAssertion`, a implantação do proxy de API falhará. Um valor de `<Issuer>` válido é necessário.

Variáveis de falha

Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
`fault.name="fault_name"`	`fault_name` é o nome da falha. O nome da falha é a última parte do código de falha.	`fault.name = "InvalidMediaTpe"`
`GenerateSAMLAssertion.failed`	Para uma configuração de política de declaração SAML válida, o prefixo do erro é `ValidateSAMLAssertion`.	`GenerateSAMLAssertion.failed = true`

Exemplo de resposta de erro

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

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

Exemplo de regra de falha

<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