In questa pagina viene descritto come attivare e utilizzare la propagazione degli attributi SAML (Security Assertion Markup Language). 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 inviarli.
Prima di iniziare
Per utilizzare la funzionalità di propagazione degli attributi SAML, devi disporre di una licenza di BeyondCorp Enterprise.
Dovresti conoscere bene la specifica SAML V2.0 Assertions and Protocols.
Comprendere 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 quale tipo di informazioni dovresti e non dovresti trasmettere su questo canale.
Puoi configurare IAP in modo da includere uno o più attributi nelle informazioni che fornisce alle applicazioni protette. Se configuri l'SSO tramite un provider di identità di terze parti e il tuo provider di identità include un <AttributeStatement>
nell'asserzione SAML, Google Cloud archivia temporaneamente gli attributi associati alla sessione dell'Account Google di un utente. Quando la sessione di un Account Google scade, un processo asincrono
rimuove definitivamente le informazioni entro una settimana. Puoi configurare la
data di scadenza.
Non utilizzare la propagazione di attributi SAML per informazioni sensibili che consentono l'identificazione personale (PII), come credenziali di account, numeri di carte d'identità, dati di titolari di carte, dati finanziari, dati sanitari o informazioni di background sensibili.
Abilitazione della propagazione degli attributi SAML
Abilita 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 e 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 propagare utilizzando il seguente formato:
attribute1, attribute2, attribute3
Puoi anche inserire gli attributi utilizzando un'espressione personalizzata.Gli attributi dell'espressione personalizzata vengono visualizzati nella scheda Attributi SAML. Devi utilizzare il seguente formato di espressione affinché gli attributi vengano visualizzati nella scheda Attributi SAML:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
In Tipi di credenziali da trasferire, seleziona almeno un formato di attributo proveniente dall'IdP da passare alle applicazioni.
gcloud
Esegui i seguenti comandi IAP gcloud CLI 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 l'applicazione.
- PROJECT: il progetto in cui si trova l'applicazione.
- RESOURCE_TYPE: il tipo di risorsa.
- SERVICE: il servizio.
- VERSION: il numero della 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 illustrato nei seguenti esempi:
{ "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 attributi su più mezzi, tra cui JWT (JSON Web Token) 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"]
Filtraggio degli attributi SAML utilizzando Common Expression Language
Puoi utilizzare le funzioni CEL (Common Expression Language) per filtrare gli attributi SAML.
L'utilizzo delle 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 scritte. L'ordine delle funzioni strict
e emitAs
non è importante quando vengono concatenate 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 proto, un elenco o un tipo di valore semplice come stringa. |
Filtraggio di elenchi | list.Filter(iter_var, condition) |
Restituisce un sottoinsieme di list in cui gli elementi soddisfano condition . |
Appartenenza all'elenco | a in b |
Restituisce true se il valore a fa parte dell'elenco b . |
selectByName | list.selectByName("name") |
Dall'elenco, seleziona l'attributo in cui name = "name" . |
append | list.append(attribute) |
Aggiunge l'attributo specificato all'elenco specificato. |
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 come output l'attributo specificato con il nome "new_name" a tutte le credenziali di output selezionate. |
Esempio di espressione CEL
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: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 sono stati modificati rispetto alle asserzioni SAML fornite.
Per l'asserzione SAML di esempio, l'IAP JWT 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 presentano URL con caratteri di escape conformi a 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 bilanciatore del carico rimuove tutte le intestazioni delle richieste con il prefisso x-goog-iap-attr
. Ciò garantisce che le intestazioni ricevute dall'app vengano generate da IAP.
Per l'asserzione SAML di esempio, l'intestazione è simile alla seguente:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
L'esempio seguente mostra in che modo IAP esegue l'escape dei caratteri speciali durante la propagazione degli attributi nelle intestazioni, come 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 escape per il nome di un'intestazione.
Nome 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"
Personalizza attributi
Puoi utilizzare le funzioni selectByName
, append
, strict
e emitas
per
modificare i nomi degli attributi propagati, specificare se utilizzare o meno il prefisso
dell'intestazione per alcuni attributi e selezionare nuovi attributi
forniti da IAP.
Se non hai bisogno della propagazione degli attributi SAML, ma ti servono l'indirizzo email,
l'ID dispositivo o il 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 le funzioni selectByName
, append
, strict
e emitas
.
Supponiamo che l'asserzione SAML di esempio.
selectByName
Utilizza la funzione selectByName
per selezionare un singolo attributo da un elenco specifico 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 aggiungerli a un elenco concatenando le aggiunte, come riportato di seguito:
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 è utile soprattutto se combinata con le funzionalità strict
e emitAs
.
strict
Utilizza la funzione strict
per segnalare un attributo in modo che IAP non preceda il nome con x-goog-iap-attr-
. Questo è utile quando il nome di un 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 che hai 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 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 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 riesce.
La maggior parte dei server web ha un limite di dimensione delle richieste di 8 kB. Questo 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 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, quindi i valori degli attributi devono essere stringhe ASCII basse. Se un'asserzione non è di tipo ASCII basso, l'accesso non riesce.