Configurar a propagação de atributo SAML

Nesta página, descrevemos como ativar e usar a propagação de atributos da Linguagem de marcação para autorização de segurança (SAML). É possível usar esse recurso para propagar atributos SAML de um provedor de identidade para aplicativos protegidos pelo Identity-Aware Proxy (IAP). Ao propagar atributos SAML, é possível especificar quais deles serão propagados e como entregar os atributos.

Antes de começar

Para usar o recurso de propagação de atributo SAML, é necessário ter uma licença do BeyondCorp Enterprise.

Você precisa conhecer a especificação de declarações e protocolos SAML V2.0.

Entender como os dados são processados

Antes de ativar a propagação de atributo SAML, verifique como o Google Cloud gerencia os dados e que tipo de informações você precisa ou não transmitir por esse canal.

É possível configurar o IAP para incluir um ou mais atributos nas informações que ele fornece aos aplicativos protegidos. Se você configurar o SSO por meio de um provedor de identidade de terceiros e seu provedor de identidade incluir um <AttributeStatement> na declaração SAML, o Google Cloud armazenará temporariamente os atributos associados à sessão da Conta do Google de um usuário. Quando uma sessão de Conta do Google expira, um processo assíncrono remove as informações permanentemente no prazo de uma semana. Você pode configurar a data de validade.

Não use a propagação de atributos SAML para informações confidenciais de identificação pessoal (PII), como credenciais de conta, números ID do governo, dados do titular do cartão, dados financeiros de contas, informações de saúde ou informações contextuais confidenciais.

Como ativar a propagação de atributo SAML

Ative a propagação de atributo SAML criando um perfil de SSO no Google Workspace e atualize as configurações do IAP usando a Google Cloud CLI ou a API REST.

Console

  1. No console do Google Cloud, acesse a página do IAP.
    Acessar o IAP
  2. Abra as configurações de um recurso e role até Propagação de atributos.
  3. Selecione Ativar propagação de atributo e clique em Salvar.

  4. Na guia SAML Attributes, digite os atributos que você quer propagar usando o seguinte formato: attribute1, attribute2, attribute3

    Também é possível inserir os atributos usando uma expressão personalizada.Os atributos da expressão personalizada são exibidos na guia SAML Attributes. Use o seguinte formato de expressão para que seus atributos sejam exibidos na guia SAML Attributes:
    attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

  5. Em Tipos de credenciais a serem transmitidas, selecione pelo menos um formato de atributo vindo do IdP para transmitir aos aplicativos.

gcloud

Execute os seguintes comandos da CLI gcloud do IAP para atualizar as configurações de propagação de atributo SAML:

gcloud iap settings set SETTING_FILE [--folder=FOLDER --organization=ORGANIZATION --project=PROJECT> --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION] [GCLOUD_WIDE_FLAG …]

Substitua:

  • FOLDER: a pasta em que o aplicativo está localizado.
  • ORGANIZATION: a organização em que o aplicativo está localizado.
  • PROJECT: o projeto em que o aplicativo reside.
  • RESOURCE_TYPE: o tipo de recurso.
  • SERVICE: o serviço.
  • VERSION: o número da versão.

YAML: 

applicationSettings:
 attributePropagationSettings:
  expression: CEL_EXPRESSION
  outputCredentials: ARRAY[OUTPUT_CREDENTIALS]
  enable: BOOLEAN

JSON: 

{
   "application_settings":{
      "attribute_propagation_settings": {
        "expression": CEL_EXPRESSION,
        "output_credentials": ARRAY[OUTPUT_CREDENTIALS]
        "enable": BOOLEAN
      }
   }
}

API REST

É possível configurar os atributos SAML para propagação usando o objeto ApplicationSettings em IapSettings, conforme mostrado nos exemplos a seguir:

{
 "csmSettings": {
    object (CsmSettings)
  },
  "accessDeniedPageSettings": {
    object (AccessDeniedPageSettings)
  },
 "attributePropagationSettings": {
    object (AttributePropagationSettings)
  },
  "cookieDomain": string,
}

AttributePropagationSettings

{
 "expression": string,
 "output_credentials": array
 "enable": boolean
}

Como configurar as credenciais de saída

Ao usar a propagação de atributo SAML, é possível enviar atributos para várias mídias, incluindo JSON Web Token (JWT) e cabeçalhos, definindo credenciais de saída. Para definir as credenciais na API, especifique uma lista de strings separadas por vírgulas, como mostrado no exemplo a seguir:

"output_credentials": ["HEADER", "JWT", "RCTOKEN"]

Como filtrar atributos SAML usando o Common Expression Language

Use as funções do Common Expression Language (CEL) para filtrar atributos SAML.

O uso de expressões CEL com propagação de atributo SAML tem as seguintes limitações:

  • Uma expressão precisa retornar uma lista de atributos.
  • Uma expressão pode selecionar, no máximo, 45 atributos.
  • Uma string de expressão não pode exceder 1.000 caracteres.

Veja a seguir as funções CEL compatíveis com o recurso de propagação de atributo SAML do IAP.

As funções diferenciam maiúsculas de minúsculas e precisam ser usadas exatamente como estão escritas. A ordem das funções strict e emitAs não importa ao encadear chamadas de função.

Função Exemplo Descrição
Seleção de campo a.b Selecione o campo b do proto a. O caractere b pode ser outro proto, uma lista ou um tipo de valor simples, como string.
Filtrar listas list.Filter(iter_var, condition) Retorna um subconjunto de list em que os itens atendem a condition.
Associação à lista a em b Retorna true se o valor a for membro da lista b.
selectByName list.selectByName("name") Na lista, selecione o atributo em que name = "name".
append list.append(attribute) Anexa o atributo fornecido à lista especificada.
strict attribute.strict() Emite o atributo sem o prefixo x-goog-iap-attr- ao usar HEADERS como uma credencial de saída.
emitAs attribute.emitAs("new_name") Mostra o atributo fornecido com o nome "new_name" para todas as credenciais de saída selecionadas.

Exemplo de expressão CEL

Considere uma declaração SAML: 

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_2">
    <saml2:AttributeValue xsi:type="xsd:string">value_3</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_4</saml2:AttributeValue>
  </saml2:Attribute>
 <saml2:Attribute Name="my_saml_attr_3">
    <saml2:AttributeValue xsi:type="xsd:string">value_5</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_6</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

Para selecionar my_saml_attr_1, use a seguinte expressão CEL:

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1"])

Para selecionar my_saml_attr_1 e my_saml_attr_2, use a seguinte expressão CEL:

attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1", "my_saml_attr_2"])

Formato do atributo

Todos os atributos selecionados estão totalmente duplicados em todas as credenciais de saída selecionadas.

Exemplo: presumir uma declaração SAML 

<saml2:AttributeStatement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <saml2:Attribute Name="my_saml_attr_1">
    <saml2:AttributeValue xsi:type="xsd:string">value_1</saml2:AttributeValue>
    <saml2:AttributeValue xsi:type="xsd:string">value_2</saml2:AttributeValue>
  </saml2:Attribute>
</saml2:AttributeStatement>

Tokens JWT e RC

O token JWT fornece os atributos por meio do campo additional_claims. O campo é um objeto e contém um mapeamento dos nomes dos atributos para uma lista dos valores dos atributos. Os nomes dos atributos não são alterados das declarações SAML fornecidas.

Para o exemplo de declaração SAML, o JWT do IAP contém o seguinte:

{
  "additional_claims": {
    "my_saml_attr_1": ["value_1", "value_2"]
  }
}

Cabeçalhos em uma declaração SAML

Nos cabeçalhos, os valores dos atributos, chaves e nomes têm escape de URL de acordo com a RFC 3986 (link em inglês) e unidos por vírgulas. Por exemplo, header&name: header$value se torna x-goog-iap-attr-header%26name: header%24value.

Para identificar exclusivamente cabeçalhos do IAP, cada cabeçalho contém o prefixo x-goog-iap-attr- do IAP. Por motivos de segurança, o balanceador de carga remove todos os cabeçalhos de solicitação com o prefixo x-goog-iap-attr. Isso garante que os cabeçalhos recebidos pelo app sejam gerados pelo IAP.

No exemplo de declaração SAML, o cabeçalho tem esta aparência:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"

O exemplo a seguir demonstra como o IAP faz o escape de caracteres especiais ao propagar atributos em cabeçalhos, como value&1, value$2 e value,3:

"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"

Confira a seguir um exemplo de como o nome de um cabeçalho é escapado.

Nome do cabeçalho:

"iap,test,3": "iap_test3_value1,iap_test3_value2"

Nome do cabeçalho com escape:

"X-Goog-IAP-Attr-iap%2Ctest%2C3": "iap_test3_value1,iap_test3_value2"

Personalizar atributos

Você pode usar as funções selectByName, append, strict e emitas para modificar os nomes dos atributos propagados, especificar se o prefixo de cabeçalho será usado ou não para alguns atributos e selecionar novos atributos fornecidos pelo IAP.

Se você não exigir a propagação de atributo SAML, mas precisar do endereço de e-mail, do ID do dispositivo ou do carimbo de data/hora em um campo SM_USER, selecione esses atributos em iap_attributes list: attributes.iap_attributes...

O IAP fornece os seguintes atributos: user_email, device_id e timestamp.

Examples

Os exemplos abaixo mostram como personalizar atributos usando as funções selectByName, append, strict e emitas.

Considere a declaração SAML de exemplo.

selectByName

Use a função selectByName para selecionar um único atributo de uma determinada lista por nome. Por exemplo, para selecionar my_saml_attr_1, use a seguinte expressão:

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

Use a função append para anexar um atributo a uma lista de atributos. É preciso selecionar esse atributo em uma das listas de atributos do IAP compatíveis. Por exemplo, para anexar my_saml_attr_2 a uma lista que contém my_saml_attr_1, use a seguinte expressão:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(attributes.saml_attributes.selectByName("my_saml_attr_2"))

É possível adicionar "my_saml_attr_2" à lista de filtros. Também é possível adicionar vários atributos e anexá-los a uma lista encadeando os anexos, da seguinte maneira:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.saml_attributes.selectByName("my_saml_attr_2")).append(
attributes.saml_attributes.selectByName("my_saml_attr_3"))

Anexar atributos únicos é mais útil quando combinado com a funcionalidade strict e emitAs.

strict

Use a função strict para sinalizar um atributo para que o IAP não use x-goog-iap-attr- como prefixo no nome. Isso é útil quando um nome de atributo precisa ser exato para o aplicativo de back-end. Exemplo:

attributes.saml_attributes.selectByName("my_saml_attr_1").strict()

emitAs

Use a função emitAs para especificar um novo nome para o atributo. O nome especificado será exibido em todas as credenciais. Por exemplo, para renomear my_saml_attr_1 como custom_name, use a seguinte expressão:

attributes.saml_attributes.selectByName("my_saml_attr_1").emitAs("custom_name")

Você pode usar as várias funções para personalizar atributos em casos de uso específicos. Por exemplo, use a expressão a seguir para propagar o e-mail de um usuário a partir de atributos do IAP como "SM_USER" com outros atributos SAML:

attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.iap_attributes.selectByName("user_email").emitAs("SM_USER").strict())

Os cabeçalhos de saída são semelhantes aos seguintes:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "email@domain.com"

Restrições ao usar a propagação de atributo SAML

No login, os atributos recebidos do provedor de identidade têm um limite de 2 KB de dados de atributo SAML. As declarações que excedem o máximo de 2 KB são recusadas, e o login falha.

A maioria dos servidores da Web tem um limite de tamanho de solicitação de 8 KB. Isso limita o tamanho dos atributos personalizados de saída, incluindo a duplicação de atributos nos cabeçalhos. Se o tamanho dos atributos (nome mais valores) exceder 5.000 bytes quando duplicados e codificados, o IAP rejeitará a solicitação e retornará o código de erro 401.

Caracteres Unicode na propagação de atributo SAML

Esse recurso não é compatível com caracteres Unicode e UTF-8. Portanto, os valores dos atributos precisam ser strings de baixa ASCII. Se uma declaração não tiver baixo ASCII, o login falhará.