Políticas de declaração SAML

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

Confira a documentação da Apigee Edge.

Ícone da política

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.

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:

  1. Se a mensagem não for XML e IgnoreContentType não estiver definido como true, uma falha será gerada.
  2. 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.
  3. 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.
  4. Assine a declaração usando a chave especificada.
  5. Adicione a declaração à mensagem no XPath especificado.

Validar declaração SAML

Processamento de políticas:

  1. 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.
  2. A política analisará o XML. Se a análise falhar, uma falha será gerada.
  3. 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.
  4. 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.
  5. 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.
  6. A política aplicará outras regras para processar as "Condições", conforme descrito na seção 2.5.1.1 do núcleo SAML.
  7. 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

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