Questa pagina è stata tradotta dall'API Cloud Translation.

Configura la propagazione degli attributi SAML

In questa pagina viene descritto come attivare e utilizzare Security Assertion Markup Language Propagazione degli attributi ( SAML). Puoi utilizzare questa funzionalità per propagare SAML di identità di un provider di identità alle applicazioni protette Identity-Aware Proxy (IAP). Quando propaghi gli attributi SAML, puoi specificare quali attributi propagare e come fornirli.

Prima di iniziare

Per utilizzare la funzionalità di propagazione degli attributi SAML, devi disporre di una licenza Chrome Enterprise Premium.

Dovresti conoscere la specifica delle asserzioni e dei protocolli SAML V2.0.

Capire come vengono gestiti i dati

Prima di attivare la propagazione degli attributi SAML, assicurati di comprendere in che modo Google Cloud gestisce i dati e il tipo di informazioni che dovresti e non devono essere trasferite su questo canale.

Puoi configurare IAP in modo da includere uno o più attributi in le informazioni che fornisce alle applicazioni protette. Se configuri SSO tramite un'identità di terze parti fornitore e il provider di identità include un <AttributeStatement> nell'asserzione SAML, Google Cloud archivia temporaneamente gli attributi associati Sessione Account Google. Quando scade la sessione di un Account Google, viene eseguita una rimuove definitivamente le informazioni entro una settimana. Puoi configurare data di scadenza.

Non utilizzare la propagazione degli attributi SAML per dati sensibili informazioni che consentono l'identificazione personale (PII), ad esempio credenziali dell'account, documenti di identità ufficiali numeri, titolari di carte di credito, dati di conti finanziari, informazioni sanitarie oppure informazioni di base sensibili.

Abilitazione della propagazione degli attributi SAML

Attiva la propagazione degli attributi SAML creando un profilo SSO in Google Workspace, quindi aggiorna le impostazioni IAP mediante Google Cloud CLI o l'API REST.

Console

Nella console Google Cloud, vai alla pagina IAP.
Vai a IAP
Apri le impostazioni per una risorsa, quindi scorri fino a Propagazione degli attributi.
Seleziona Abilita la propagazione degli attributi, quindi fai clic su Salva.
Nella scheda Attributi SAML, inserisci gli attributi che vuoi si propagano utilizzando il seguente formato: attribute1, attribute2, attribute3

Puoi anche inserire gli attributi utilizzando un'espressione personalizzata. gli attributi della tua espressione personalizzata vengono visualizzati nell'account Scheda Attributi. Per le tue query, devi utilizzare il seguente formato di espressione: da visualizzare nella scheda Attributi SAML:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
Per Tipi di credenziali da trasmettere, seleziona almeno un formato di attributo provenienti dall'IdP per passarle alle applicazioni.

gcloud

Esegui i seguenti comandi della gcloud CLI IAP per aggiornare le impostazioni di propagazione degli attributi SAML:

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

Sostituisci quanto segue:

FOLDER: la cartella in cui si trova l'applicazione.
ORGANIZATION: l'organizzazione in cui risiede la tua applicazione.
PROJECT: il progetto in cui si trova l'applicazione.
RESOURCE_TYPE: il tipo di risorsa.
SERVICE: il servizio.
VERSION: il numero di versione.

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

Puoi configurare la propagazione degli attributi SAML utilizzando l'oggetto ApplicationSettings in IapSettings, come mostrato negli esempi seguenti:

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

AttributePropagationSettings

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

Impostazione delle credenziali di output

Quando utilizzi la propagazione degli attributi SAML, puoi inviare gli attributi su più mezzi, tra cui il token web JSON (JWT) e le intestazioni, impostando le credenziali di output. Per impostare le credenziali nell'API, puoi specificare un elenco di stringhe separate da virgole, come mostrato nell'esempio seguente:

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

Filtro degli attributi SAML utilizzando Common Expression Language

Puoi utilizzare le funzioni Common Expression Language (CEL) per filtrare gli attributi SAML.

L'utilizzo di espressioni CEL con la propagazione degli attributi SAML presenta le seguenti limitazioni:

Un'espressione deve restituire un elenco di attributi.
Un'espressione può selezionare un massimo di 45 attributi.
Una stringa di espressione non può superare i 1000 caratteri.

Di seguito sono riportate le funzioni CEL supportate quando si utilizza la funzionalità di propagazione degli attributi SAML IAP.

Tieni presente che le funzioni sono sensibili alle maiuscole e devono essere utilizzate esattamente come sono scritte. L'ordine delle funzioni strict e emitAs non è importante quando si concatenano le chiamate di funzione.

Funzione	Esempio	Descrizione
Selezione campi	`a.b`	Seleziona il campo `b` dal protocollo `a`. Il carattere `b` può essere un altro protocollo, un elenco o un tipo di valore semplice come stringa.
Filtrare elenchi	`list.Filter(iter_var, condition)`	Restituisce un sottoinsieme di `list` in cui gli elementi soddisfano `condition`.
Appartenenza elenco	`a` in `b`	Restituisce `true` se il valore `a` è un membro dell'elenco `b`.
selectByName	`list.selectByName("name")`	Dall'elenco, seleziona l'attributo in cui `name = "name"`.
Aggiunta	`list.append(attribute)`	Aggiunge l'attributo specificato all'elenco fornito.
livello massimo	`attribute.strict()`	Emette l'attributo senza il prefisso `x-goog-iap-attr-` quando utilizzi `HEADERS` come credenziale di output.
emitAs	`attribute.emitAs("new_name")`	Restituisce l'attributo specificato con il nome `"new_name"` a tutte le credenziali di output selezionate.

Espressione CEL di esempio

Presupponi un'asserzione 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>

Per selezionare my_saml_attr_1, utilizza la seguente espressione CEL:

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

Per selezionare my_saml_attr_1 e my_saml_attr_2, utilizza la seguente espressione CEL:

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

Formato attributo

Tutti gli attributi selezionati sono completamente duplicati in tutte le credenziali di output selezionate.

Esempio: supponi un'asserzione 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

Il token JWT fornisce gli attributi tramite il campo additional_claims. Il campo è un oggetto e contiene una mappatura dei nomi degli attributi a un elenco di valori degli attributi. I nomi degli attributi non cambiano rispetto alle asserzioni SAML fornite.

Per l'esempio di asserzione SAML, il JWT IAP contiene seguenti:

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

Intestazioni in un'asserzione SAML

Nelle intestazioni, i valori degli attributi, delle chiavi e dei nomi contengono caratteri di escape tramite URL. secondo RFC 3986 e unito dalla virgole. Ad esempio, header&name: header$value diventa x-goog-iap-attr-header%26name: header%24value.

Per identificare in modo univoco le intestazioni IAP, ogni intestazione contiene la Prefisso IAP x-goog-iap-attr-. Per motivi di sicurezza, il carico il bilanciatore rimuove qualsiasi intestazione delle richieste con il prefisso x-goog-iap-attr. Questo assicura che le intestazioni ricevute dall'app siano generate da IAP.

Per l'esempio di asserzione SAML, l'intestazione ha il seguente aspetto:

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

L'esempio seguente mostra come IAP esegue l'escape di speciale durante la propagazione degli attributi nelle intestazioni, ad esempio value&1, value$2, e value,3:

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

Di seguito è riportato un esempio dei caratteri di escape per il nome di un'intestazione.

Nome intestazione:

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

Nome dell'intestazione con caratteri di escape:

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

Personalizza attributi

Puoi utilizzare le funzioni selectByName, append, strict e emitas per modificare i nomi degli attributi propagati, specificare se utilizzare o meno l’intestazione per alcuni attributi e seleziona il nuovo IAP attributi.

Se non hai bisogno della propagazione degli attributi SAML, ma hai bisogno dell'indirizzo email, ID dispositivo o timestamp in un campo SM_USER, puoi selezionare questi attributi da iap_attributes list: attributes.iap_attributes...

IAP fornisce i seguenti attributi: user_email, device_id e timestamp.

Esempi

I seguenti esempi mostrano come personalizzare gli attributi utilizzando il metodo Funzioni selectByName, append, strict e emitas.

Supponi di avere l'esempio di asserzione SAML.

selectByName

Utilizza la funzione selectByName per selezionare un singolo attributo da un determinato elenco in base al nome. Ad esempio, per selezionare my_saml_attr_1, utilizza la seguente espressione:

attributes.saml_attributes.selectByName("my_saml_attr_1")

append

Utilizza la funzione append per aggiungere un attributo a un elenco di attributi. Devi selezionare questo attributo da uno degli elenchi di attributi IAP supportati. Ad esempio, per aggiungere my_saml_attr_2 a un elenco contenente my_saml_attr_1, utilizza la seguente espressione:

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

Puoi aggiungere "my_saml_attr_2" all'elenco di filtri. Puoi anche aggiungere più attributi e aggiungerli a un elenco concatenando le appendici, come seguenti:

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

L'aggiunta di singoli attributi è più utile se combinata con strict e emitAs.

strict

Utilizza la funzione strict per contrassegnare un attributo in modo che IAP non aggiunge il prefisso x-goog-iap-attr- al nome. Ciò è utile quando deve essere esatto per l'applicazione di backend. Esempio:

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

emitAs

Utilizza la funzione emitAs per specificare un nuovo nome per l'attributo. Il nome che verrà inviato a tutte le credenziali. Ad esempio, per rinominare Da my_saml_attr_1 a custom_name, utilizza la seguente espressione:

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

Puoi utilizzare le varie funzioni per personalizzare gli attributi per casi d'uso specifici. Ad esempio, puoi utilizzare la seguente espressione per propagare l'email di un utente dagli attributi IAP come "SM_USER" insieme ad altri attributi SAML:

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

Le intestazioni di output hanno il seguente aspetto:

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

Vincoli durante l'utilizzo della propagazione degli attributi SAML

Al momento dell'accesso, gli attributi in entrata dal provider di identità hanno un limite di 2 kB dei dati degli attributi SAML. Le asserzioni che superano il limite massimo di 2 kB vengono rifiutate e l'accesso non riesce.

La maggior parte dei server web ha un limite di dimensione delle richieste di 8 kB. Ciò limita le dimensioni attributi personalizzati in uscita, inclusa la duplicazione degli attributi nelle intestazioni. Se la dimensione degli attributi (nome più valori) supera i 5000 byte se duplicati e codificato, IAP rifiuta la richiesta e restituisce Codice di errore IAP 401.

Caratteri Unicode nella propagazione degli attributi SAML

Questa funzione non supporta i caratteri Unicode e UTF-8, quindi i valori degli attributi devono essere stringhe con caratteri ASCII bassi. Se un'asserzione non ha un carattere ASCII basso, l'accesso non riesce.