Política GenerateSAMLAssertion

Política extensível

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

Confira Apigee Edge documentação.

A política GenerateSAMLAssertion permite que os proxies de API anexem declarações SAML a solicitações XML de saída. Essas declarações ficam disponíveis para que os serviços de back-end apliquem mais processamento de segurança para autenticação e autorização. Consulte Visão geral das políticas SAML para mais informações.

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

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

Referência de elemento

Esta seção lista os elementos e atributos da política GenerateSAMLAssertion.

Atributos que se aplicam ao elemento de nível superior

<GenerateSAMLAssertion name="SAML-A1" continueOnError="false" enabled="true" async="false">

Os seguintes atributos são comuns a todos os elementos pai de política.

Atributo Descrição Padrão Presença
nome O nome interno da política. 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.

Opcionalmente, use o elemento <displayname></displayname> para rotular a política no editor de proxy da IU da Apigee com um nome de linguagem natural diferente.

 N/A Obrigatório
ativado Defina como true para aplicar a política.

Defina como false para "desativar" a política. A política não será aplicada mesmo se permanecer anexada a um fluxo.

 verdadeiro Opcional

Elementos e atributos para geração de declaração SAML

Nome do campo Descrição
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
Especifica onde a declaração SAML gerada será colocada. A declaração pode ser armazenada em uma variável de fluxo ou inserida em uma mensagem existente.
FlowVariable
Especifica o nome da variável de fluxo em que o conteúdo da declaração SAML gerada será armazenado. Essa é uma alternativa ao uso do elemento <Message> para inserir a declaração em uma mensagem XML existente.
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 opcional ref 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 não 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.

Observações sobre uso

Processamento de políticas:

  1. Se a mensagem não for XML e ignoreContentType não estiver definido como true, então uma falha será gerada.
  2. Se Template 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 Template 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.

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