Políticas de declaração SAML

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

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.

Amostras

<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="test">http://www.example.com/test</Namespace>
      </Namespaces>
      <XPath>/envelope/header</XPath>
    </Message>
  </OutputVariable>
  <SignatureAlgorithm />
  <Subject ref="reference">Subject name</Subject>
  <Template ignoreUnresolvedVariables="false">
    <!-- A lot of XML goes here, in CDATA, with {} around
         each variable -->
  </Template>
</GenerateSAMLAssertion>

<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

Gerar declaração SAML

Validar declaração SAML

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 confirmar se o tipo de mídia da solicitação é XML, verificação 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 vai gerar uma falha.
2. A política analisará o XML. Se a análise falhar, uma falha será gerada.
3. A política vai extrair o elemento assinado e a declaração usando os respectivos XPaths. especificado (<SignedElementXPath> e <AssertionXPath>). Se um desses caminhos não retornar um elemento, a política vai gerar uma falha.
4. a política verificará se a declaração é igual ao elemento assinado; ou é filho do elemento assinado. Se isso não for verdade, a política emitirá uma falha.
5. Se <NotBefore> ou <NotOnOrAfter> estiverem presentes na declaração, a política verificará o carimbo de data/hora atual em relação esses valores, conforme descrito na seção 2.5.1 do Núcleo do SAML.
6. A política vai aplicar outras regras para processar as "Condições". conforme descrito na seção principal do SAML 2.5.1.1.
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.

Referência de erros

Esta seção descreve os códigos de falha e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando esta 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 essa política.

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.

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