Políticas de SAMLAssertion

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

Veja a documentação do Apigee Edge.

A política SAMLAssertion permite que os proxies de API validem as afirmações SAML anexadas a pedidos SOAP de entrada ou anexem afirmações SAML a pedidos XML de saída. A política SAML valida as mensagens recebidas que contêm uma afirmaçã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 afirmação.

  • Autenticação e autorização de entrada: política de validação de declarações 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
name atributo 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.
ignoreContentType atributo 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 opcional ref 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 KeyStore 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 o pedido e, quando anexada ao fluxo de respostas, a política resolve message para a resposta.
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 tempo de 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.

Valide a declaração SAML

Nome do campo Descrição
name atributo
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.
ignoreContentType atributo 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 pode ser diferente ou igual ao XPath de 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 afirmaçã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 afirmaçã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 declaraçã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 declaração, convertido do respetivo tipo XML nativo para uma string
saml.subject O "Subject" 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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
SourceNotConfigured One or more of the following elements of the ValidateSAMLAssertion policy is not defined or empty: <Source>, <XPath>, <Namespaces>, <Namespace>.
TrustStoreNotConfigured If the <TrustStore> element is empty or not specified in the ValidateSAMLAssertion policy, then the deployment of the API proxy fails. A valid truststore is required.
NullKeyStoreAlias If the child element <Alias> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid keystore alias is required.
NullKeyStore If the child element <Name> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid keystore name is required.
NullIssuer If the <Issuer> element is empty or not specified in the GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid <Issuer> value is required.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault. The fault name is the last part of the fault code. fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed For a validate SAML assertion policy configuration, the error prefix is ValidateSAMLAssertion. GenerateSAMLAssertion.failed = true

Example error response

{
  "fault": {
    "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type",
    "detail": {
      "errorcode": "steps.saml.generate.InvalidMediaTpe"
    }
  }
}

Example fault rule

<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