Configurar a propagação de atributos 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). Use 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 atributos propagar e como entregá-los.

Observação: a propagação de atributos SAML é compatível com identidades do Google que usam o Logon Único (SSO) com um provedor de identidade SAML de terceiros no Google Workspace ou no Cloud Identity. A propagação de atributos SAML não é compatível com aplicativos configurados para usar o IAP com a federação de identidade de colaboradores.

Antes de começar

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

Como os dados são tratados

Antes de ativar a propagação de atributos SAML, entenda como oGoogle Cloud gerencia os dados e que tipo de informação você deve e não deve 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 usando um provedor de identidade de terceiros e seu provedor de identidade incluir um <AttributeStatement> na declaração SAML, oGoogle Cloud armazenará temporariamente os atributos associados à sessão da Conta do Google de um usuário. Quando uma sessão da Conta do Google expira, um processo assíncrono remove permanentemente as informações em uma semana. É possível configurar a data de validade.

Não use a propagação de atributos SAML para informações sensíveis de identificação pessoal (PII), como dados de acesso à conta, números ID governamentais, dados do titular do cartão, dados financeiros da conta, informações sobre saúde ou informações prévias confidenciais.

Como ativar a propagação de atributos SAML

Ative a propagação de atributos 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.

Observação: quando você ativa esse recurso para usuários ou grupos de usuários específicos, sua configuração atual do SAML é substituída.

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 atributos e clique em Salvar.

4. Na guia Atributos SAML, insira 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 sua expressão personalizada são exibidos na guia Atributos SAML. Use o seguinte formato de expressão para que os atributos sejam exibidos na guia Atributos SAML:
   attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

5. Em Tipos de credencial a serem transmitidos, selecione pelo menos um formato de atributo proveniente 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 atributos 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á.

• ORGANIZATION: a organização em que o aplicativo reside.

• PROJECT: o projeto em que o aplicativo está.

• 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 definir as credenciais de saída

Ao usar a propagação de atributos SAML, é possível enviar atributos por vários meios, 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 a Common Expression Language

É possível usar as funções da Common Expression Language (CEL) para filtrar atributos SAML.

O uso de expressões CEL com a propagação de atributos 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.

Confira a seguir as funções CEL compatíveis com o recurso de propagação de atributos 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 uma string.
Como filtrar listas	list.Filter(iter_var, condition)	Retorna um subconjunto de list em que os itens atendem a condition.
Listar assinaturas	a em b	Retorna true se o valor a for um 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 fornecida.
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")	Gera o atributo fornecido com o nome "new_name" para todas as credenciais de saída selecionadas.

Exemplo de expressão CEL

Suponha 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 são totalmente duplicados em todas as credenciais de saída selecionadas.

Exemplo: assumir 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>

Token JWT e RC

O token JWT fornece os atributos pelo 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 nas 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 são escapados por URL de acordo com a RFC 3986 e unidos por vírgulas. Por exemplo, header&name: header$value torna-se x-goog-iap-attr-header%26name: header%24value.

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

Para o exemplo de declaração SAML, o cabeçalho é semelhante a este:

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

Veja a seguir um exemplo de como um nome de 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 personalizados

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

Se você não precisar da propagação de atributos 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 na lista iap_attributes: attributes.iap_attributes…

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

Exemplos

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

Considere o exemplo de declaração SAML.

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. Selecione 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 as adições, como no exemplo a seguir:

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

Adicionar atributos únicos ao final é mais útil quando combinado com as funcionalidades strict e emitAs.

strict

Use a função strict para sinalizar um atributo para que o IAP não use o prefixo x-goog-iap-attr- no nome. Isso é útil quando um nome do 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á gerado para 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")

É possível usar as várias funções para personalizar atributos para casos de uso específicos. Por exemplo, use a seguinte expressão para propagar o e-mail de um usuário dos atributos do IAP como "SM_USER", junto 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 assim:

"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "[e-mail]"

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

No login, os atributos recebidos do provedor de identidade têm um limite de 2 KB de dados de atributos 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 em cabeçalhos. Se o tamanho dos atributos (nome e valores) exceder 5.000 bytes quando duplicados e codificados, o IAP rejeitará a solicitação e retornará o código do erro 401 do IAP.

Caracteres Unicode na propagação de atributos SAML

Esse recurso não é compatível com caracteres Unicode e UTF-8. Portanto, os valores de atributo precisam ser strings ASCII baixas. Se uma declaração não for de baixo ASCII, o login vai falhar.