Esta página foi traduzida pela API Cloud Translation.

Políticas de SAMLAssertion

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

O quê

Autenticação e autorização de entrada: política de validação de declaração SAML
O tipo de política SAML permite que os proxies de API validem declarações SAML anexadas a pedidos SOAP de entrada. A política SAML valida as mensagens recebidas que contêm uma declaração SAML com assinatura digital, rejeita-as se forem inválidas e define variáveis que permitem que políticas adicionais ou os próprios serviços de back-end validem ainda mais as informações na declaração.
Geração de tokens de saída: política de geração de afirmações SAML
O tipo de política SAML permite que os proxies de API anexem afirmações SAML a pedidos XML de saída. Essas afirmações ficam então disponíveis para permitir que os serviços de back-end apliquem um processamento de segurança adicional para autenticação e autorização.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Amostras

Gere uma afirmaçã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>

Gerar uma afirmação SAML

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

Validar uma declaração SAML

Referência do elemento

Gere uma afirmação SAML

Nome do campo	Descrição
Atributo `name`	O nome da instância da política. O nome tem de ser exclusivo na organização. Os carateres que pode usar no nome estão restritos a: `A-Z0-9._\-$ %`. No entanto, a IU do Apigee aplica restrições adicionais, como a remoção automática de carateres que não sejam alfanuméricos.
Atributo `ignoreContentType`	Um booleano que pode ser definido como `true` ou `false`. Por predefinição, a declaração não é gerada se o tipo de conteúdo da mensagem não for um tipo de conteúdo XML. Se esta opção estiver definida como `true`, a mensagem é tratada como XML, independentemente do tipo de conteúdo.
`Issuer`	O identificador exclusivo do fornecedor de identidade. Se o atributo `ref` opcional estiver presente, o valor de Issuer é atribuído no momento da execução com base na variável especificada. Se o atributo opcional `ref` não estiver presente, é usado o valor de Issuer.
`KeyStore`	O nome do armazenamento de chaves que contém a chave privada e o alias da chave privada usados para assinar digitalmente as afirmações SAML.
`OutputVariable`
`FlowVariable`
`Message`	O alvo da política. Os valores válidos são `message`, `request`, e `response`. Quando definida como `message`, a política obtém condicionalmente o objeto de mensagem com base no ponto de anexação da política. Quando anexada ao fluxo de pedidos, a política resolve `message` para pedir e, quando anexada ao fluxo de respostas, 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 vai anexar a declaração SAML.
`SignatureAlgorithm`	SHA1 ou SHA256
`Subject`	O identificador exclusivo do assunto da declaração SAML. Se o atributo opcional `ref` estiver presente, o valor de Subject é atribuído no momento da execução com base na variável especificada. Se o atributo opcional `ref` estiver presente, é usado o valor de Subject.
`Template`	Se estiver presente, a declaração é gerada executando este modelo, substituindo tudo o que estiver indicado com `{}` pela variável correspondente e, em seguida, assinando digitalmente o resultado. O modelo é processado de acordo com as regras da política AssignMessage. Consulte a política AssignMessage. O elemento `<Template>` suporta a funcionalidade de substituição de strings dinâmicas denominada modelos de mensagens. Os modelos de mensagens só são suportados quando a assinatura da política é `GenerateSamlAssertion`.

Valide a declaração SAML

Nome do campo	Descrição
Atributo `name`	O nome da instância da política. O nome tem de ser exclusivo na organização. Os carateres que pode usar no nome estão restritos a: `A-Z0-9._\-$ %`. No entanto, a IU do Apigee aplica restrições adicionais, como a remoção automática de carateres que não sejam alfanuméricos.
Atributo `ignoreContentType`	Um booleano que pode ser definido como `true` ou `false`. Por predefinição, a declaração não é gerada se o tipo de conteúdo da mensagem não for um tipo de conteúdo XML. Se esta opção estiver definida como `true`, a mensagem é tratada como XML independentemente do tipo de conteúdo.
`Source`	O alvo da política. Os valores válidos são `message`, `request`, e `response`. Quando definida como `message`, a política obtém condicionalmente o objeto de mensagem com base no ponto de anexação da política. Quando anexada ao fluxo de pedidos, a política resolve `message` para `request` e, quando anexada ao fluxo de respostas, a política resolve `message` para `response`.
`XPath`	Descontinuado. Filho de `Source`. Use `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. Este elemento pode ser diferente ou igual ao XPath do elemento `AssertionXPath`.
`TrustStore`	O nome do TrustStore que contém certificados X.509 fidedignos usados para validar assinaturas digitais em afirmações SAML.
`RemoveAssertion`	Um booleano que pode ser definido como `true` ou `false`. Quando `true`, a declaração SAML é removida da mensagem de pedido antes de a mensagem ser encaminhada para o serviço de back-end.

Notas de utilização

A especificação da Linguagem de marcação de declaração de segurança (SAML) define formatos e protocolos que permitem que as aplicações troquem informações formatadas em XML para autenticação e autorização.

Uma "afirmação de segurança" é um token fidedigno que descreve um atributo de uma app, um utilizador da app ou algum outro participante numa transação. As afirmações de segurança são geridas e consumidas por dois tipos de entidades:

Fornecedores de identidade: geram afirmações de segurança em nome dos participantes
Fornecedores de serviços: validam as afirmações de segurança através de relações fidedignas com fornecedores de identidade

A plataforma de API pode atuar como um fornecedor de identidade e como um fornecedor de serviços. Funciona como um fornecedor de identidade gerando afirmações e anexando-as a mensagens de pedido, disponibilizando essas afirmações para processamento por serviços de back-end. Funciona como um fornecedor de serviços ao validar afirmações em mensagens de pedidos recebidas.

O tipo de política SAML suporta afirmaçõ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.

Gere uma afirmação SAML

Processamento de políticas:

Se a mensagem não for XML e IgnoreContentType não estiver definido como true, então gera uma falha.
Se "Template" estiver definido, processe o modelo conforme descrito para a política AssignMessage. Se faltarem variáveis e IgnoreUnresolvedVariables não estiver definido, é gerado um erro.
Se "Template" não estiver definido, construa uma afirmação que inclua os valores dos parâmetros Subject e Issuer ou as respetivas referências.
Assine a declaração com a chave especificada.
Adicione a declaração à mensagem no XPath especificado.

Valide a declaração SAML

Processamento de políticas:

A política verifica a mensagem recebida para confirmar se o tipo de suporte do pedido é XML, através da verificação se o tipo de conteúdo corresponde aos formatos text/(.*+)?xml ou application/(.*+)?xml. Se o tipo de suporte não for XML e <IgnoreContentType> não estiver definido, a política vai gerar uma falha.
A política vai analisar o XML. Se a análise falhar, é gerado um erro.
A política extrai o elemento assinado e a afirmação, usando os XPaths respetivos especificados (<SignedElementXPath> e <AssertionXPath>). Se qualquer um destes caminhos não devolver um elemento, a política gera uma falha.
A política vai verificar se a declaração é igual ao elemento assinado ou se é um elemento subordinado do elemento assinado. Se não for verdade, a política gera uma falha.
Se qualquer um dos elementos <NotBefore> ou <NotOnOrAfter> estiver presente na declaração, a política verifica a data/hora atual em função destes valores, conforme descrito na secção 2.5.1 do SAML Core.
A política aplica quaisquer regras adicionais para o processamento das "Condições", conforme descrito na secção 2.5.1.1 do SAML Core.
A política valida a assinatura digital XML através dos valores de <TrustStore> e <ValidateSigner>, conforme descrito acima. Se a validação falhar, a política gera uma falha.

Assim que a política for concluída sem gerar uma falha, o programador do proxy pode ter a certeza do seguinte:

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

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

Variáveis de fluxo

Existem muitas informações que podem ser especificadas numa declaração SAML. A declaração SAML em si é XML que pode ser analisado através da política ExtractVariables e de 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 afirmação, convertido do respetivo tipo XML nativo para uma string
`saml.subject`	O "Assunto" da declaração, convertido do respetivo tipo XML nativo para uma string
`saml.valid`	Devolve 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`	Morada dos dados de confirmação do titular
`saml.scdinresponse`	Dados de confirmação do assunto na resposta
`saml.scdrcpt`	Destinatário de dados de confirmação do titular
`saml.authnSnooa`	AuthnStatement SessionNotOnOrAfter
`saml.authnContextClassRef`	AuthnStatement AuthnContextClassRef
`saml.authnInstant`	AuthnStatement AuthInstant
`saml.authnSessionIndex`	Índice da sessão AuthnStatement

Referência de erro

Esta secção descreve os códigos de falhas e as mensagens de erro devolvidas e as variáveis de falhas definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Nome do erro	Causa	Corrigir
`SourceNotConfigured`	Um ou mais dos seguintes elementos da política `ValidateSAMLAssertion` não estão definidos ou estão vazios: `<Source>`, `<XPath>`, `<Namespaces>`, `<Namespace>`.
`TrustStoreNotConfigured`	Se o elemento `<TrustStore>` estiver vazio ou não for especificado na política `ValidateSAMLAssertion`, a implementação do proxy de API falha. É necessário um repositório de confiança válido.
`NullKeyStoreAlias`	Se o elemento secundário `<Alias>` estiver vazio ou não for especificado no elemento `<Keystore>` da política `GenerateSAMLAssertion`, a implementação do proxy da API falha. É necessário um alias do keystore válido.
`NullKeyStore`	Se o elemento secundário `<Name>` estiver vazio ou não for especificado no elemento `<Keystore>` da política `GenerateSAMLAssertion`, a implementação do proxy da API falha. É necessário um nome de keystore válido.
`NullIssuer`	Se o elemento `<Issuer>` estiver vazio ou não for especificado na política `GenerateSAMLAssertion`, a implementação do proxy de API falha. É necessário um valor `<Issuer>` válido.

Variáveis de falha

Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

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 validação de afirmação SAML, o prefixo de erro é `ValidateSAMLAssertion`.	`GenerateSAMLAssertion.failed = true`

Exemplo de resposta de erro

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque 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>

Tópicos relacionados

Extração de variáveis: política de extração de variáveis