Configura la propagazione degli attributi SAML

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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 propaga gli attributi SAML, puoi specificare quali attributi propagare e come pubblicare gli attributi.

Prima di iniziare

Per utilizzare la funzionalità di propagazione dell'attributo SAML, devi disporre di una licenza BeyondCorp Enterprise.

Dovresti conoscere la specifica SAML V2.0 Assertions and Protocols.

Comprendere il modo in cui 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 per includere uno o più attributi nelle informazioni che fornisce alle tue applicazioni protette. Se configuri 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 archivia temporaneamente gli attributi associati alla sessione dell'Account Google di un utente. Alla scadenza di una sessione di un Account Google, 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 che consentono l'identificazione personale (PII) sensibili, come credenziali dell'account, numeri di carte d'identità, dati di titolari di carte, dati di conti finanziari, dati sanitari o informazioni di base sensibili.

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.

gcloud

Esegui i seguenti comandi dell'interfaccia a riga di comando gcloud di IAP per aggiornare le impostazioni di propagazione dell'attributo 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: 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ù mezzi, 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 illustrato nell'esempio seguente:

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

Filtrare gli attributi SAML utilizzando il linguaggio delle espressioni comuni

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

L'utilizzo di espressioni CEL con propagazione dell'attributo 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 che sono 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'ordinamento delle funzioni strict e emitAs non è rilevante durante la concatenazione delle chiamate della funzione.

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

Esempio di espressione CEL

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: supponiamo che sia presente 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'asserzione SAML di esempio, il JWT di 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 con caratteri di escape URL in base 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 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 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 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 di un nome di 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 hai bisogno dell'indirizzo email, dell'ID dispositivo o del timestamp in un campo SM_USER, puoi selezionare questi attributi dal 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.

Presupponi l'esempio di asserzione SAML.

selectByName

Utilizza la funzione selectByName per selezionare un singolo attributo di 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 inserirli in un elenco concatenando le appendici, 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 è particolarmente utile se combinata con le funzionalità strict e emitAs.

strict

Utilizza la funzione strict per contrassegnare un attributo in modo che IAP non faccia precedere il nome da 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 specificato verrà inviato a 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 in base ai 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 quando si utilizza la propagazione degli attributi SAML

Al momento dell'accesso, gli attributi in entrata del 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 per la richiesta di 8 kB. Questo limita la dimensione degli attributi personalizzati in uscita, tra cui gli attributi duplicati nelle intestazioni. Se le dimensioni degli attributi (nome più valori) superano i 5000 byte quando vengono duplicati e codificati, IAP rifiuta la richiesta e restituisce il codice di errore IAP 401.

Caratteri Unicode nella propagazione dell'attributo 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 è ASCII bassa, l'accesso non riesce.