Auf dieser Seite wird beschrieben, wie Sie die Attributweitergabe von SAML (Security Assertion Markup Language) aktivieren und verwenden. Mit diesem Feature können Sie SAML-Attribute von einem Identitätsanbieter an Anwendungen weitergeben, die durch Identity-Aware Proxy (IAP) geschützt sind. Beim Propagieren von SAML-Attributen können Sie angeben, welche Attribute weitergegeben werden sollen und wie die Attribute übermittelt werden sollen.
Hinweise
Wenn Sie die Funktion zur Weitergabe von SAML-Attributen verwenden möchten, benötigen Sie eine BeyondCorp Enterprise-Lizenz.
Sie sollten mit der SAML V2.0 Assertions and Protocols-Spezifikation vertraut sein.
Verstehen, wie die Daten verarbeitet werden
Bevor Sie die SAML-Attributweitergabe aktivieren, sollten Sie sich damit vertraut machen, wie Google Cloud die Daten verwaltet und welche Art von Informationen Sie über diesen Kanal weitergeben sollten und welche nicht.
Sie können IAP so konfigurieren, dass ein oder mehrere Attribute in die Informationen aufgenommen werden, die für Ihre geschützten Anwendungen bereitgestellt werden. Wenn Sie die SSO über einen externen Identitätsanbieter einrichten und Ihr Identitätsanbieter ein <AttributeStatement> in die SAML-Assertion einfügt, speichert Google Cloud vorübergehend die Attribute, die mit der Google-Kontositzung eines Nutzers verknüpft sind. Wenn eine Sitzung mit einem Google-Konto abläuft, werden die Informationen durch einen asynchronen Prozess innerhalb einer Woche endgültig entfernt. Sie können das Ablaufdatum konfigurieren.
Verwenden Sie die Weitergabe von SAML-Attributen nicht für vertrauliche personenidentifizierbare Informationen (PII), wie z. B. Anmeldedaten für Konten, Behörden-ID-Nummern, Karteninhaberdaten, Bankkontodaten, Gesundheitsdaten oder vertrauliche Hintergrundinformationen.
Weitergabe von SAML-Attributen aktivieren
Aktivieren Sie die Weitergabe von SAML-Attributen, indem Sie in Google Workspace ein SSO-Profil erstellen. Aktualisieren Sie dann die IAP-Einstellungen über die Google Cloud CLI oder die REST API.
Console
- Rufen Sie in der Google Cloud Console die Seite „IAP“ auf.
Zu IAP - Öffnen Sie die Einstellungen für eine Ressource und scrollen Sie zu Attributweitergabe.
- Wählen Sie Attributweitergabe aktivieren aus und klicken Sie dann auf Speichern.
Geben Sie auf dem Tab SAML Attributes (SAML-Attribute) die Attribute im folgenden Format ein, die Sie übertragen möchten:
attribute1, attribute2, attribute3Sie können die Attribute auch mit einem benutzerdefinierten Ausdruck eingeben.Die Attribute für Ihren benutzerdefinierten Ausdruck werden auf dem Tab SAML-Attribute angezeigt. Sie müssen das folgende Ausdrucksformat verwenden, damit Ihre Attribute auf dem Tab SAML-Attribute angezeigt werden:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])Wählen Sie unter Zu übergebende Anmeldedaten mindestens ein Attributformat vom IdP aus, der an Anwendungen übergeben werden soll.
gcloud
Führen Sie die folgenden Befehle für gcloud CLI-Befehlszeile aus, um die Einstellungen für die Weitergabe von SAML-Attributen zu aktualisieren:
gcloud iap settings set SETTING_FILE [--folder=FOLDER --organization=ORGANIZATION --project=PROJECT> --resource-type=RESOURCE_TYPE --service=SERVICE --version=VERSION] [GCLOUD_WIDE_FLAG …]
Ersetzen Sie Folgendes:
- FOLDER: Der Ordner, in dem sich Ihre Anwendung befindet.
- ORGANIZATION: Die Organisation, in der sich Ihre Anwendung befindet.
- PROJECT: Das Projekt, in dem sich Ihre Anwendung befindet.
- RESOURCE_TYPE: Der Ressourcentyp.
- SERVICE: Der Dienst.
- VERSION: Die Versionsnummer.
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
}
}
}
REST API
Sie können die Weitergabe der SAML-Attribute mithilfe des Objekts ApplicationSettings in IapSettings konfigurieren, wie in den folgenden Beispielen gezeigt:
{
"csmSettings": {
object (CsmSettings)
},
"accessDeniedPageSettings": {
object (AccessDeniedPageSettings)
},
"attributePropagationSettings": {
object (AttributePropagationSettings)
},
"cookieDomain": string,
}
AttributePropagationSettings
{
"expression": string,
"output_credentials": array
"enable": boolean
}
Anmeldedaten für die Ausgabe festlegen
Bei der SAML-Attributweitergabe können Sie Attribute über mehrere Medien senden, einschließlich JSON Web Token (JWT) und Header, indem Sie Ausgabeanmeldedaten festlegen. Um die Anmeldedaten in der API festzulegen, können Sie eine Liste kommagetrennter Strings angeben, wie im folgenden Beispiel gezeigt:
"output_credentials": ["HEADER", "JWT", "RCTOKEN"]
SAML-Attribute mit Common Expression Language filtern
Sie können die CEL-Funktionen (Common Expression Language) verwenden, um SAML-Attribute zu filtern.
Bei der Verwendung von CEL-Ausdrücken mit der SAML-Attribut-Weitergabe gelten folgende Einschränkungen:
- Ein Ausdruck muss eine Liste von Attributen zurückgeben.
- Ein Ausdruck kann maximal 45 Attribute auswählen.
- Ein Ausdrucksstring darf nicht länger als 1.000 Zeichen sein.
Im Folgenden sind die CEL-Funktionen aufgeführt, die bei Verwendung der IAP-Funktion zur Weitergabe von Attributen unterstützt werden.
Bei den Funktionen wird zwischen Groß- und Kleinschreibung unterschieden und sie müssen genau so verwendet werden, wie geschrieben. Die Reihenfolge der Funktionen strict und emitAs spielt beim Verketten von Funktionsaufrufen keine Rolle.
| Funktion | Beispiel | Beschreibung |
|---|---|---|
| Feldauswahl | a.b |
Wählen Sie das Feld b aus dem Proto-a aus. Das Zeichen b kann ein anderes Proto, eine Liste oder ein einfacher Werttyp wie ein String sein. |
| Listen filtern | list.Filter(iter_var, condition) |
Gibt eine Teilmenge von list zurück, wobei Elemente mit condition übereinstimmen. |
| Listenmitgliedschaft | "a" in "b" |
Gibt true zurück, wenn der Wert a ein Mitglied der Liste b ist. |
| selectByName | list.selectByName("name") |
Wählen Sie aus der Liste das Attribut mit name = "name" aus. |
| append | list.append(attribute) |
Hängt das angegebene Attribut an die angegebene Liste an. |
| strikt | attribute.strict() |
Gibt das Attribut ohne das Präfix x-goog-iap-attr- aus, wenn HEADERS als Ausgabeanmeldedaten verwendet wird. |
| emitAs | attribute.emitAs("new_name") |
Gibt das angegebene Attribut mit dem Namen "new_name" an alle ausgewählten Ausgabeanmeldedaten aus. |
CEL-Beispielausdruck
Von einer SAML-Assertion ausgehen:
<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>
Verwenden Sie den folgenden CEL-Ausdruck, um my_saml_attr_1 auszuwählen:
attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1"])
Verwenden Sie den folgenden CEL-Ausdruck, um my_saml_attr_1 und my_saml_attr_2 auszuwählen:
attributes.saml_attributes.filter(attribute, attribute.name in ["my_saml_attr_1", "my_saml_attr_2"])
Attributformat
Alle ausgewählten Attribute werden in allen ausgewählten Ausgabeanmeldedaten vollständig dupliziert.
Beispiel: Von einer SAML-Assertion ausgehen
<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 und RC-Token
Das JWT-Token stellt die Attribute über das Feld additional_claims bereit. Das -Feld ist ein Objekt und enthält eine Zuordnung der Attributnamen zu einer Liste mit Attributwerten. Die Attributnamen und die bereitgestellten SAML-Assertions haben sich nicht geändert.
Für die SAML-Beispielinstanz enthält das IAP-JWT Folgendes:
{
"additional_claims": {
"my_saml_attr_1": ["value_1", "value_2"]
}
}
Header in einer SAML-Assertion
In Headern werden die Werte der Attribute, Schlüssel und Namen gemäß RFC 3986 mit URL-Escape-Zeichen versehen und durch Kommas verknüpft. Aus header&name: header$value wird beispielsweise x-goog-iap-attr-header%26name: header%24value.
Zur eindeutigen Identifizierung von IAP-Headern enthält jeder Header das IAP-Präfix x-goog-iap-attr-. Aus Sicherheitsgründen entfernt der Load-Balancer alle Anfrageheader mit dem Präfix x-goog-iap-attr. Dadurch wird sichergestellt, dass von der Anwendung empfangene Header von IAP generiert werden.
Für das Beispiel für eine SAML-Assertion sieht der Header so aus:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
Das folgende Beispiel zeigt, wie IAP Sonderzeichen umgeht, wenn Attribute in Headern wie value&1, value$2 und value,3 weitergegeben werden:
"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"
Das folgende Beispiel zeigt, wie ein Headername maskiert wird.
Header name:
"iap,test,3": "iap_test3_value1,iap_test3_value2"
Maskierter Headername:
"X-Goog-IAP-Attr-iap%2Ctest%2C3": "iap_test3_value1,iap_test3_value2"
Attribute anpassen
Mit den Funktionen selectByName, append, strict und emitas können Sie die weitergegebenen Attributnamen ändern, angeben, ob für einige Attribute das Headerpräfix verwendet werden soll, und neue von IAP bereitgestellte Attribute auswählen.
Wenn keine SAML-Attributweitergabe erforderlich ist, Sie aber die E-Mail-Adresse, die Geräte-ID oder den Zeitstempel in einem SM_USER-Feld benötigen, können Sie diese Attribute aus iap_attributes list auswählen: attributes.iap_attributes...
IAP bietet die folgenden Attribute: user_email, device_id und timestamp.
Beispiele
Die folgenden Beispiele zeigen, wie Attribute mithilfe der Funktionen selectByName, append, strict und emitas angepasst werden.
Sehen wir uns die Beispiel-SAML-Assertion an.
selectByName
Verwenden Sie die Funktion selectByName, um ein einzelnes Attribut aus einer Liste anhand des Namens auszuwählen. Verwenden Sie beispielsweise den folgenden Ausdruck, um my_saml_attr_1 auszuwählen:
attributes.saml_attributes.selectByName("my_saml_attr_1")
append
Verwenden Sie die Funktion append, um ein Attribut an eine Liste von Attributen anzuhängen. Sie müssen dieses Attribut aus einer der unterstützten IAP-Attributlisten auswählen. Wenn Sie beispielsweise my_saml_attr_2 an eine Liste anhängen möchten, die my_saml_attr_1 enthält, verwenden Sie den folgenden Ausdruck:
attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(attributes.saml_attributes.selectByName("my_saml_attr_2"))
Du kannst „"my_saml_attr_2"“ der Filterliste hinzufügen. Sie können auch mehrere Attribute hinzufügen und an eine Liste anhängen, indem Sie die Anfügungen wie folgt verketten:
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"))
Das Anfügen einzelner Attribute ist am nützlichsten, wenn sie mit den Funktionen strict und emitAs kombiniert wird.
strict
Verwenden Sie die Funktion strict, um ein Attribut zu markieren, sodass dem Namen von IAP nicht x-goog-iap-attr- vorangestellt wird. Dies ist nützlich, wenn ein Attributname für die Back-End-Anwendung genau sein muss. Beispiel:
attributes.saml_attributes.selectByName("my_saml_attr_1").strict()
emitAs
Verwenden Sie die Funktion emitAs, um einen neuen Namen für das Attribut anzugeben. Der von Ihnen angegebene Name wird an alle Anmeldedaten ausgegeben. Wenn Sie beispielsweise my_saml_attr_1 in custom_name umbenennen möchten, verwenden Sie den folgenden Ausdruck:
attributes.saml_attributes.selectByName("my_saml_attr_1").emitAs("custom_name")
Sie können die verschiedenen Funktionen verwenden, um Attribute für bestimmte Anwendungsfälle anzupassen. Mit dem folgenden Ausdruck können Sie beispielsweise die E-Mail-Adresse eines Nutzers aus den IAP-Attributen als "SM_USER" zusammen mit anderen SAML-Attributen weitergeben:
attributes.saml_attributes.filter(x, x.name in ["my_saml_attr_1"]).append(
attributes.iap_attributes.selectByName("user_email").emitAs("SM_USER").strict())
Die Ausgabeheader sehen so aus:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "email@domain.com"
Einschränkungen bei der Weitergabe von SAML-Attributen
Bei der Anmeldung sind für vom Identitätsanbieter eingehende Attribute auf 2 KB an SAML-Attributdaten beschränkt. Assertions, die die maximale Größe von 2 KB überschreiten, werden abgelehnt und die Anmeldung schlägt fehl.
Die meisten Webserver haben eine Größenbeschränkung von 8 KB für Anfragen. Dadurch wird die Größe ausgehender benutzerdefinierter Attribute begrenzt, einschließlich der Duplizierung von Attributen in Headern. Wenn die Größe der Attribute (Name plus Werte) beim Duplizieren und Codieren 5.000 Byte überschreitet, lehnt IAP die Anfrage ab und gibt den IAP-Fehlercode 401 zurück.
Unicode-Zeichen bei der Weitergabe von SAML-Attributen
Von dieser Funktion werden keine Unicode- und UTF-8-Zeichen unterstützt. Daher müssen Attributwerte Low-ASCII-Strings sein. Wenn eine Assertion nicht Low-ASCII ist, schlägt die Anmeldung fehl.