Esta página descreve como ativar e usar a Linguagem de marcação para autorização de segurança (SAML). Você pode usar esse recurso para propagar SAML atributos de um provedor de identidade para aplicativos protegidos por Identity-Aware Proxy (IAP). Ao propagar atributos SAML, é possível especificar quais atributos serão propagados e como eles serão entregues.
Antes de começar
Para usar o recurso de propagação de atributo SAML, você precisa ter uma licença do Chrome Enterprise Premium.
Você precisa conhecer a especificação de declarações e protocolos SAML V2.0.
Entender como os dados são tratados
Antes de ativar a propagação de atributos SAML, entenda como o Google Cloud gerencia os dados e que tipo de informação pode ou não ser transmitida por esse canal.
É possível configurar o IAP para incluir um ou mais atributos no
as informações fornecidas aos aplicativos protegidos. Se você configurar
SSO por meio de uma identidade de terceiros
provedor e
seu provedor de identidade incluir um <AttributeStatement>
na asserção SAML;
O Google Cloud armazena temporariamente os atributos associados à conta
sessão da Conta do Google. Quando uma sessão da Conta do Google expira, uma
remove permanentemente as informações em uma semana. É possível configurar
ou a data de validade.
Não use a propagação de atributos SAML para dados confidenciais pessoais informações de identificação pessoal (PII), como credenciais de contas e ID números de telefone, dados do titular do cartão, dados financeiros de contas, informações de saúde ou informações confidenciais contextuais.
Como ativar a propagação de atributo 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 CLI do Google Cloud ou a API REST.
Console
- No console do Google Cloud, acesse a página do IAP.
Acessar o IAP - Abra as configurações de um recurso e role até Propagação do atributo.
- Selecione Ativar propagação de atributo e clique em Salvar.
Na guia SAML Attributes, insira os atributos que você quer propagadas pelo seguinte formato:
attribute1, attribute2, attribute3
Também é possível inserir os atributos usando uma expressão personalizada. da sua expressão personalizada são mostrados no documento Atributos. Use o seguinte formato de expressão para seu atributos que serão exibidos na guia SAML Attributes:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
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 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 reside.
- 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
Você pode configurar a propagação dos atributos SAML 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, você pode enviar atributos em 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, conforme mostrado no exemplo a seguir:
"output_credentials": ["HEADER", "JWT", "RCTOKEN"]
Como filtrar atributos SAML usando a Common Expression Language
Você pode usar as funções 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 até 45 atributos.
- Uma string de expressão não pode exceder 1.000 caracteres.
Confira a seguir as funções CEL com suporte ao recurso de propagação de atributos SAML do IAP.
Observe que as funções diferenciam maiúsculas de minúsculas e precisam ser usadas exatamente como foram 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 no a proto. O caractere b pode ser outro proto, uma lista ou um tipo de valor simples, como string. |
Como 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 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 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") |
Envia o atributo especificado 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: 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>
JWT e token 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 de valores do atributo. Os nomes dos atributos não foram alterados em relação às declarações SAML fornecidas.
Para o exemplo de declaração SAML, o JWT do IAP contém o seguintes:
{
"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 codificados por URL
de acordo com o 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 forma exclusiva os cabeçalhos do IAP, cada cabeçalho contém o
prefixo x-goog-iap-attr-
do IAP. Por motivos de segurança, a carga
balanceador 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 a seguinte aparência:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
O exemplo a seguir demonstra como o IAP escapa
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 fazer o escape de um nome de cabeçalho.
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
Use as funções selectByName
, append
, strict
e emitas
para
modificar os nomes dos atributos propagados, especificar se deve ou não usar o cabeçalho
para alguns atributos e selecione o novo prefixo fornecido pelo IAP
atributos.
Se você não precisar da propagação de atributos SAML, mas precisar do endereço de e-mail,
ID do dispositivo ou carimbo de data/hora em um campo SM_USER, selecione esses atributos
do iap_attributes list
: 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 o
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 lista específica 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. Você precisa selecionar esse atributo em uma das listas de atributos do IAP aceitas. 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. Você também pode adicionar
vários atributos e anexá-los a uma lista encadeando os anexos, como o
seguintes:
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 o strict
e a funcionalidade emitAs
.
strict
Use a função strict
para sinalizar um atributo para que o IAP
não tem o prefixo x-goog-iap-attr-
no nome. Isso é útil quando um
O 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 que você
especificar serão exibidas em todas as credenciais. Por exemplo, para renomear
my_saml_attr_1
a custom_name
, use a seguinte expressão:
attributes.saml_attributes.selectByName("my_saml_attr_1").emitAs("custom_name")
Você pode usar as diversas funções para personalizar atributos para casos de uso específicos. Por exemplo, é possível usar 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 semelhantes a este:
"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 de entrada do provedor de identidade têm um limite de 2 KB. de dados de atributo SAML. As declarações que excederem o máximo de 2 KB serão recusadas e falha no login.
A maioria dos servidores da Web tem um limite de tamanho de solicitação de 8 KB. Isso limita o tamanho atributos personalizados de saída, incluindo a duplicação de atributos em cabeçalhos. Se o dos atributos (nome mais valores) excede 5.000 bytes quando duplicados e codificado, o IAP rejeita a solicitação e retorna o Código de erro 401 do IAP.
Caracteres Unicode na propagação de atributos SAML
Este recurso não suporta caracteres Unicode e UTF-8, portanto, os valores dos atributos devem ser com pouco ASCII. Se uma declaração não tiver ASCII baixo, o login falhará.