Questa pagina descrive come attivare e utilizzare la propagazione degli attributi Security Assertion Markup Language (SAML). Puoi utilizzare questa funzionalità per propagare gli attributi SAML da un provider di identità alle applicazioni protette da Identity-Aware Proxy (IAP). Quando propaghi gli attributi SAML, puoi specificare quali attributi propagare e come.
Prima di iniziare
Per utilizzare la funzionalità di propagazione degli attributi SAML, devi disporre di una licenza Chrome Enterprise Premium.
Devi conoscere la specifica delle asserzioni e dei protocolli SAML 2.0.
Informazioni su come vengono gestiti i dati
Prima di attivare la propagazione degli attributi SAML, assicurati di comprendere come Google Cloud gestisce i dati e quali tipi di informazioni devi e non devi trasmettere tramite questo canale.
Puoi configurare l'IAP in modo da includere uno o più attributi nelle informazioni fornite alle tue applicazioni protette. Se hai configurato il servizio SSO tramite un provider di identità di terze parti e il tuo provider di identità include un <AttributeStatement> nell'asserzione SAML, Google Cloud memorizza temporaneamente gli attributi associati alla sessione dell'Account Google di un utente. Quando una sessione dell'Account Google scade, un processo asincrono rimuove definitivamente le informazioni entro una settimana. Puoi configurare la data di scadenza.
Non utilizzare la propagazione degli attributi SAML per informazioni personali sensibili (PII) come credenziali dell'account, numeri di documenti di identità, dati di titolari delle carte, dati finanziari, dati sanitari o informazioni di carattere generale riservate.
Attivazione della propagazione degli attributi SAML
Attiva la propagazione degli attributi SAML creando un profilo SSO in Google Workspace, quindi aggiorna le impostazioni IAP utilizzando Google Cloud CLI o l'API REST.
Console
- Nella console Google Cloud, vai alla pagina IAP.
Vai a IAP - Apri le impostazioni di una risorsa, quindi scorri fino a Propagazione degli attributi.
- Seleziona Attiva la propagazione degli attributi e poi fai clic su Salva.
Nella scheda Attributi SAML, inserisci gli attributi da propagare utilizzando il seguente formato:
attribute1, attribute2, attribute3Puoi anche inserire gli attributi utilizzando un'espressione personalizzata.Gli attributi per l'espressione personalizzata vengono visualizzati nella scheda Attributi SAML. Devi utilizzare il seguente formato dell'espressione per visualizzare gli attributi nella scheda Attributi SAML:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])Per Tipi di credenziali da passare, seleziona almeno un formato dell'attributo proveniente dall'IdP da passare alle applicazioni.
gcloud
Esegui i seguenti comandi gcloud CLI per l'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 risiede l'applicazione.
- ORGANIZATION: l'organizzazione in cui risiede la tua applicazione.
- PROJECT: il progetto in cui risiede la tua 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 gli attributi SAML da propagare 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ù supporti, inclusi token web JSON (JWT) e 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"]
Filtrare gli 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 espressioni 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 scritte. L'ordine delle funzioni strict e emitAs non è importante quando si collegano le chiamate alle funzioni.
| Funzione | Esempio | Descrizione |
|---|---|---|
| Selezione dei campi | a.b |
Seleziona il campo b dal proto a. Il carattere b può essere un altro proto, un elenco o un semplice tipo di valore come una stringa. |
| Elenchi di filtri | list.Filter(iter_var, condition) |
Restituisce un sottoinsieme di list in cui gli elementi soddisfano condition. |
| Elenco appartenenza | a in b |
Restituisce true se il valore a è un elemento dell'elenco b. |
| selectByName | list.selectByName("name") |
Nell'elenco, seleziona l'attributo in cui name = "name". |
| Aggiunta | list.append(attribute) |
Collega l'attributo specificato all'elenco specificato. |
| rigoroso | attribute.strict() |
Emette l'attributo senza il prefisso x-goog-iap-attr- quando utilizzi HEADERS come credenziale di output. |
| emitAs | attribute.emitAs("new_name") |
Consente di esportare l'attributo specificato con il nome "new_name" in tutte le credenziali di output selezionate. |
Espressione CEL di esempio
Supponiamo un'affermazione 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 dell'attributo
Tutti gli attributi selezionati sono completamente duplicati in tutte le credenziali di output selezionate.
Esempio: Supponiamo un'affermazione 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 dei relativi valori. I nomi degli attributi non sono stati modificati rispetto alle asserzioni SAML fornite.
Per l'affermazione SAML di esempio, il JWT IAP contiene quanto segue:
{
"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 sono codificati per gli URL
secondo la specifica RFC 3986 e uniti da 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 il prefisso IAP x-goog-iap-attr-. Per motivi di sicurezza, il bilanciamento del carico rimuove tutte le intestazioni di richiesta con il prefisso x-goog-iap-attr. In questo modo,
si garantisce che le intestazioni ricevute dall'app siano generate da IAP.
Per l'affermazione SAML di esempio, l'intestazione è la seguente:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
L'esempio seguente mostra come IAP esegue la fuga di caratteri speciali quando propaga gli 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 di come viene eseguito l'escape del nome di un'intestazione.
Nome dell'intestazione:
"iap,test,3": "iap_test3_value1,iap_test3_value2"
Nome intestazione con caratteri di escape:
"X-Goog-IAP-Attr-iap%2Ctest%2C3": "iap_test3_value1,iap_test3_value2"
Personalizzare gli attributi
Puoi utilizzare le funzioni selectByName, append, strict e emitas per modificare i nomi degli attributi propagati, specificare se utilizzare o meno il prefisso della intestazione per alcuni attributi e selezionare nuovi attributi forniti dall'IAP.
Se non hai bisogno della propagazione degli attributi SAML, ma hai bisogno dell'indirizzo email, dell'ID dispositivo o del 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
Gli esempi seguenti mostrano come personalizzare gli attributi utilizzando le funzioni selectByName, append, strict e emitas.
Supponiamo l'asserzione SAML di esempio.
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 dei filtri. Puoi anche aggiungere più attributi e accodarli a un elenco concatenandoli, ad esempio:
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 le funzionalità strict
e emitAs.
strict
Utilizza la funzione strict per segnalare un attributo in modo che la funzionalità IAP
non aggiunga il prefisso x-goog-iap-attr- al nome. Questo è utile quando un nome di attributo 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 specificato verrà visualizzato in tutte le credenziali. Ad esempio, per rinominare
my_saml_attr_1 in 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 sono le seguenti:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "email@domain.com"
Limitazioni relative all'utilizzo della propagazione degli attributi SAML
Al momento dell'accesso, gli attributi in arrivo dal provider di identità hanno un limite di 2 KB di dati degli attributi SAML. Le asserzioni che superano il limite massimo di 2 KB vengono rifiutate e l'accesso non va a buon fine.
La maggior parte dei server web ha un limite di dimensioni delle richieste di 8 KB. Ciò limita le dimensioni degli attributi personalizzati in uscita, inclusa la duplicazione degli attributi nelle intestazioni. Se la dimensione degli attributi (nome più valori) supera i 5000 byte quando vengono duplicati e codificati, IAP rifiuta la richiesta e restituisce il codice di errore IAP 401.
Caratteri Unicode nella propagazione degli attributi SAML
Questa funzionalità non supporta i caratteri Unicode e UTF-8, pertanto i valori degli attributi devono essere stringhe con caratteri ASCII minuscoli. Se un'affermazione non è in ASCII minuscolo, l'accesso non va a buon fine.