Política ValidateSAMLAssertion

Política extensível

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

Confira a documentação da Apigee Edge.

A política ValidateSAMLAssertion 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 define 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. Consulte Visão geral das políticas de SAML para mais informações.

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

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

Referência de elemento

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

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 o atributo ignoreContentType não estiver definido como true, a política vai 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 valida a assinatura digital XML usando o valor do repositório de confiança (<TrustStore>) descrito acima. Se a validação falhar, a política vai gerar 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

Política ValidateSAMLAssertion Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Amostras

Referência de elemento

Validar declaração SAML

Observações sobre uso

Variáveis de fluxo

Referência de erros

Erros de implantação

Variáveis de falha

Exemplo de resposta de erro

Exemplo de regra de falha

Temas relacionados

Política ValidateSAMLAssertion