Configure a propagação de atributos SAML

Esta página descreve como ativar e usar a propagação de atributos da linguagem de marcação de declaração de segurança (SAML). Pode usar esta funcionalidade para propagar atributos SAML de um fornecedor de identidade para aplicações protegidas pelo Identity-Aware Proxy (IAP). Quando propaga atributos SAML, pode especificar os atributos a propagar e como entregar os atributos.

Antes de começar

Deve ter conhecimentos sobre a especificação de protocolos e afirmações SAML V2.0 (PDF).

Compreender como os dados são tratados

Antes de ativar a propagação de atributos SAML, certifique-se de que compreende como a Google Cloud gere os dados e que tipo de informações deve e não deve transmitir através deste canal.

Pode configurar o IAP para incluir um ou mais atributos nas informações que fornece às suas aplicações protegidas. Se configurar o SSO através de um fornecedor de identidade de terceiros e o seu fornecedor de identidade incluir um <AttributeStatement> na declaração SAML, o Google Cloud armazena temporariamente os atributos associados a uma sessão da Conta Google de um utilizador. Quando uma sessão da Conta Google expira, um processo assíncrono remove permanentemente as informações no prazo de uma semana. Pode configurar a data de validade.

Não use a propagação de atributos SAML para informações de identificação pessoal (IIP) confidenciais, como credenciais de contas, números de identificação emitidos por entidades governamentais, dados de titulares de cartões, dados de contas financeiras, informações de cuidados de saúde ou informações confidenciais em segundo plano.

Ativar a propagação de atributos SAML

Ative a propagação de atributos SAML criando um perfil de SSO no Google Workspace e, em seguida, atualize as definições do IAP através da CLI Google Cloud ou da API REST.

Consola

  1. Na Google Cloud consola, aceda à página de CNAs.
    Aceder a CNA
  2. Abra as definições de um recurso e, de seguida, desloque a página até Propagação de atributos.
  3. Selecione Ativar propagação de atributos e, de seguida, clique em Guardar.

  4. No separador Atributos SAML, introduza os atributos que quer propagar com o seguinte formato: attribute1, attribute2, attribute3

    Também pode introduzir os atributos através de uma expressão personalizada.Os atributos da sua expressão personalizada são apresentados no separador Atributos SAML. Tem de usar o seguinte formato de expressão para que os seus atributos sejam apresentados no separador Atributos SAML:
    attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])

  5. Para Tipos de credenciais a transmitir, selecione, pelo menos, um formato de atributo proveniente do IdP para transmitir às aplicações.

gcloud

Execute os seguintes comandos da CLI gcloud do IAP para atualizar as definiçõ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 o seguinte:

  • FOLDER: a pasta onde reside a sua aplicação.
  • ORGANIZATION: a organização na qual a sua aplicação reside.
  • PROJECT: o projeto no qual a sua aplicação 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

Pode configurar os atributos SAML para propagação através do objeto ApplicationSettings em IapSettings, conforme mostrado nos exemplos seguintes:

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

AttributePropagationSettings

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

Definir as credenciais de saída

Quando usa a propagação de atributos SAML, pode enviar atributos em vários meios, incluindo o símbolo da Web JSON (JWT) e cabeçalhos, definindo credenciais de saída. Para definir as credenciais na API, pode especificar uma lista de strings separadas por vírgulas, conforme mostrado no exemplo seguinte:

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

Filtrar atributos SAML através do idioma de expressão comum

Pode usar funções do Idioma de expressão comum (IEC) para filtrar atributos SAML.

A utilização de expressões de IEC com a propagação de atributos SAML tem as seguintes limitações:

  • Uma expressão tem de devolver uma lista de atributos.
  • Uma expressão pode selecionar um máximo de 45 atributos.
  • Uma string de expressão não pode exceder 1000 carateres.

Seguem-se as funções de IEC suportadas quando usa a funcionalidade de propagação de atributos SAML do IAP.

Tenha em atenção que as funções são sensíveis a maiúsculas e minúsculas e têm de ser usadas exatamente como estão escritas. A ordem das funções strict e emitAs não é importante quando encadeia chamadas de funções.

Função Exemplo Descrição
Seleção de campos a.b Selecione o campo b do proto a. O caráter b pode ser outro proto, uma lista ou um tipo de valor simples, como uma string.
Filtrar listas list.Filter(iter_var, condition) Devolve um subconjunto de list onde os itens cumprem a condição condition.
Membros da lista a em b Devolve true se o valor a for um membro da lista b.
selectByName list.selectByName("name") Na lista, selecione o atributo onde name = "name".
anexar list.append(attribute) Anexa o atributo indicado à lista indicada.
rigoroso attribute.strict() Emite o atributo sem o prefixo x-goog-iap-attr- quando usa HEADERS como credencial de saída.
emitAs attribute.emitAs("new_name") Envia o atributo indicado com o nome "new_name" para todas as credenciais de saída selecionadas.

Exemplo de expressão de IEC

Assumir uma afirmaçã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 de IEC:

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 de IEC:

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: assume a SAML assertion 

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

JWT e token RC

O token JWT fornece os atributos através 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 permanecem inalterados em relação às afirmações SAML fornecidas.

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

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

Cabeçalhos numa declaração SAML

Nos cabeçalhos, os valores dos atributos, das chaves e dos 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 exclusivamente os cabeçalhos de IAP, cada cabeçalho contém o prefixo x-goog-iap-attr- IAP. Por motivos de segurança, o balanceador de carga remove todos os cabeçalhos de pedidos com o prefixo x-goog-iap-attr. Isto garante que os cabeçalhos recebidos pela app são gerados pela IAP.

Para o exemplo de declaração SAML, o cabeçalho tem o seguinte aspeto:

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

O exemplo seguinte demonstra como a CNA escapa a carateres especiais quando propaga 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"

Segue-se 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 carateres de escape:

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

Personalize atributos

Pode usar as funções selectByName, append, strict e emitas para modificar os nomes dos atributos propagados, especificar se deve ou não usar o prefixo do cabeçalho para alguns atributos e selecionar novos atributos fornecidos pela IAP.

Se não precisar da propagação de atributos SAML, mas precisar do endereço de email, do ID do dispositivo ou da data/hora num campo SM_USER, pode selecionar esses atributos em iap_attributes list: attributes.iap_attributes…

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

Exemplos

Os exemplos seguintes mostram como personalizar atributos através das funções selectByName, append, strict e emitas.

Suponha 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. Tem de selecionar este atributo a partir de uma das listas de atributos de IAP suportadas. Por exemplo, para acrescentar my_saml_attr_2 a uma lista que contenha 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"))

Pode adicionar "my_saml_attr_2" à lista de filtros. Também pode adicionar vários atributos e anexá-los a uma lista encadeando os anexos, como no exemplo seguinte:

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

A anexação de atributos únicos é mais útil quando combinada com a funcionalidade strict e emitAs.

strict

Use a função strict para sinalizar um atributo de modo que a IAP não adicione o prefixo x-goog-iap-attr- ao nome. Isto é útil quando um nome de atributo tem de ser exato para a aplicação 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 que especificar é apresentado em todas as credenciais. Por exemplo, para mudar o nome de my_saml_attr_1 para custom_name, use a seguinte expressão:

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

Pode usar as várias funções para personalizar atributos para exemplos de utilização específicos. Por exemplo, pode usar a seguinte expressão para propagar o email de um utilizador dos atributos do IAP como "SM_USER" juntamente 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 têm o seguinte aspeto:

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

No início de sessão, os atributos recebidos do fornecedor de identidade têm um limite de 2 KB de dados de atributos SAML. As afirmações que excedam o máximo de 2 KB são recusadas e o início de sessão falha.

A maioria dos servidores Web tem um limite de tamanho de solicitação de 8 KB. Isto 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 5000 bytes quando duplicado e codificado, a IAP rejeita o pedido e devolve o código de erro da IAP 401.

Carateres Unicode na propagação de atributos SAML

Esta funcionalidade não suporta carateres Unicode nem UTF-8, pelo que os valores dos atributos têm de ser strings ASCII baixas. Se uma afirmação não for ASCII inferior, o início de sessão falha.