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:

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

Valide a declaração SAML

Processamento de políticas:

1. 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.
2. A política vai analisar o XML. Se a análise falhar, é gerado um erro.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.

Sugestão: precisa de ajuda para resolver um erro? Clique em na coluna Corrigir para ver informações detalhadas de resolução de problemas.

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