Auf dieser Seite wird beschrieben, wie Sie die SAML-Attributweitergabe (Security Assertion Markup Language) aktivieren und verwenden. Mit dieser Funktion können Sie SAML-Attribute von einem Identitätsanbieter an Anwendungen weitergeben, die durch Identity-Aware Proxy (IAP) geschützt sind. Wenn Sie SAML-Attribute weitergeben, können Sie angeben, welche Attribute weitergegeben werden sollen und wie die Attribute bereitgestellt werden sollen.
Hinweise
Sie sollten mit der SAML V2.0-Spezifikation für Assertions und Protokolle (PDF) vertraut sein.
So werden die Daten verarbeitet
Bevor Sie die SAML-Attributweitergabe aktivieren, sollten Sie sich darüber im Klaren sein, wieGoogle 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 den Informationen enthalten sind, die für Ihre geschützten Anwendungen bereitgestellt werden. Wenn Sie die Einmalanmeldung (SSO) über einen externen Identitätsanbieter eingerichtet haben und Ihr Identitätsanbieter ein <AttributeStatement> in der SAML-Assertion enthält, speichertGoogle Cloud die Attribute, die der Google-Konto-Sitzung eines Nutzers zugeordnet sind, vorübergehend. Wenn eine Google-Kontositzung abläuft, werden die Informationen innerhalb einer Woche durch einen asynchronen Prozess endgültig entfernt. Sie können das Ablaufdatum konfigurieren.
Verwenden Sie die SAML-Attributweitergabe nicht für vertrauliche personenidentifizierbare Informationen wie Anmeldedaten für Konten, behördliche Identifikationsnummern, Karteninhaberdaten, Finanzdaten, Gesundheitsdaten oder vertrauliche Hintergrundinformationen.
SAML-Attributweitergabe aktivieren
Aktivieren Sie die SAML-Attributweitergabe, indem Sie ein SSO-Profil in Google Workspace erstellen und dann die IAP-Einstellungen mit der Google Cloud CLI oder der REST API aktualisieren.
Console
- Rufen Sie in der Google Cloud Console die IAP-Seite 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-Attribute die Attribute ein, die Sie im folgenden Format weitergeben 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 für Ihre Attribute verwenden, damit sie auf dem Tab SAML-Attribute angezeigt werden:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])Wählen Sie unter Zu übergebende Anmeldedatentypen mindestens ein Attributformat aus, das vom IdP stammt und an Anwendungen übergeben werden soll.
gcloud
Führen Sie die folgenden IAP-gcloud CLI-Befehle aus, um die Einstellungen für die SAML-Attributweitergabe 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 ist 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 SAML-Attribute für die Weitergabe mit dem Objekt 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
}
Ausgabeanmeldedaten festlegen
Wenn Sie die SAML-Attributweitergabe verwenden, können Sie Attribute über mehrere Medien hinweg senden, einschließlich JSON Web Token (JWT) und Headern, indem Sie Ausgabedaten festlegen. Wenn Sie die Anmeldedaten in der API festlegen möchten, können Sie eine Liste mit durch Kommas getrennten Strings angeben, wie im folgenden Beispiel gezeigt:
"output_credentials": ["HEADER", "JWT", "RCTOKEN"]
SAML-Attribute mit der Common Expression Language filtern
Sie können CEL-Funktionen (Common Expression Language) verwenden, um SAML-Attribute zu filtern.
Die Verwendung von CEL-Ausdrücken mit der SAML-Attributweitergabe unterliegt den folgenden Einschränkungen:
- Ein Ausdruck muss eine Liste von Attributen zurückgeben.
- In einem Ausdruck können maximal 45 Attribute ausgewählt werden.
- Ein Ausdrucksstring darf nicht länger als 1.000 Zeichen sein.
Im Folgenden finden Sie die CEL-Funktionen, die bei Verwendung der Funktion zur Weitergabe von IAP-SAML-Attributen unterstützt werden.
Bei den Funktionen wird zwischen Groß- und Kleinschreibung unterschieden. Sie müssen genau wie geschrieben verwendet werden. 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 „string“ sein. |
| Listen filtern | list.Filter(iter_var, condition) |
Gibt eine Teilmenge von list zurück, in der die Elemente condition entsprechen. |
| Listenmitgliedschaft | „a“ in „b“ |
Gibt true zurück, wenn der Wert a ein Element der Liste b ist. |
| selectByName | list.selectByName("name") |
Wählen Sie in der Liste das Attribut aus, für das name = "name". |
| append | list.append(attribute) |
Hängt das angegebene Attribut an die angegebene Liste an. |
| streng | attribute.strict() |
Gibt das Attribut ohne das Präfix x-goog-iap-attr- aus, wenn HEADERS als Ausgabeberechtigungsnachweis verwendet wird. |
| emitAs | attribute.emitAs("new_name") |
Gibt das angegebene Attribut mit dem Namen "new_name" für alle ausgewählten Ausgabedaten aus. |
Beispiel für einen CEL-Ausdruck
Angenommen, Sie haben eine SAML-Assertion:
<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 Ausweisdokumenten vollständig dupliziert.
Beispiel: Eine SAML-Assertion annehmen
<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 der Attributwerte. Die Attributnamen sind gegenüber den bereitgestellten SAML-Assertions unverändert.
Für die Beispiel-SAML-Assertion 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 URL-codiert und durch Kommas getrennt. Aus header&name: header$value wird beispielsweise x-goog-iap-attr-header%26name: header%24value.
Um IAP-Headern eine eindeutige Kennung zuzuweisen, 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. So wird sichergestellt, dass die von der App empfangenen Header von IAP generiert werden.
Für die Beispiel-SAML-Assertion sieht der Header so aus:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
Im folgenden Beispiel sehen Sie, wie IAP Sonderzeichen wie value&1, value$2 und value,3 beim Weitergeben von Attributen in Headern maskiert:
"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"
Im Folgenden sehen Sie ein Beispiel dafür, wie ein Headername maskiert wird.
Header name:
"iap,test,3": "iap_test3_value1,iap_test3_value2"
Escaped header name:
"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 Namen der weitergegebenen Attribute ändern, angeben, ob für einige Attribute das Header-Präfix verwendet werden soll, und neue von IAP bereitgestellte Attribute auswählen.
Wenn Sie keine SAML-Attributweitergabe benötigen, aber die E-Mail-Adresse, Geräte-ID oder den Zeitstempel in einem SM_USER-Feld benötigen, können Sie diese Attribute über iap_attributes list attributes.iap_attributes auswählen.
IAP bietet die folgenden Attribute: user_email, device_id und timestamp.
Beispiele
In den folgenden Beispielen wird gezeigt, wie Sie Attribute mit den Funktionen selectByName, append, strict und emitas anpassen.
Nehmen wir die Beispiel-SAML-Assertion an.
selectByName
Mit der Funktion selectByName können Sie ein einzelnes Attribut aus einer bestimmten Liste anhand des Namens auswählen. Wenn Sie beispielsweise my_saml_attr_1 auswählen möchten, verwenden Sie den folgenden Ausdruck:
attributes.saml_attributes.selectByName("my_saml_attr_1")
append
Mit der Funktion append können Sie einer Liste von Attributen ein Attribut hinzufügen. Sie müssen dieses Attribut aus einer der unterstützten Listen mit IAP-Attributen auswählen. Wenn Sie beispielsweise my_saml_attr_2 an eine Liste mit my_saml_attr_1 anhängen möchten, 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"))
Sie können der Filterliste "my_saml_attr_2" hinzufügen. Sie können auch mehrere Attribute hinzufügen und sie an eine Liste anhängen, indem Sie die Anhänge verketten, wie im folgenden Beispiel:
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 Anhängen einzelner Attribute ist am nützlichsten in Kombination mit den Funktionen strict und emitAs.
strict
Mit der Funktion strict können Sie ein Attribut kennzeichnen, damit IAP dem Namen nicht das Präfix x-goog-iap-attr- voranstellt. Das ist nützlich, wenn ein Attributname für die Backend-Anwendung genau sein muss. Beispiel:
attributes.saml_attributes.selectByName("my_saml_attr_1").strict()
emitAs
Mit der Funktion emitAs können Sie einen neuen Namen für das Attribut angeben. Der von Ihnen angegebene Name wird in allen 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")
Mit den verschiedenen Funktionen können Sie Attribute für bestimmte Anwendungsfälle anpassen. Mit dem folgenden Ausdruck können Sie beispielsweise die E-Mail-Adresse eines Nutzers aus 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 Ausgabekopfzeilen sehen so aus:
"x-goog-iap-attr-my_saml_attr_1": "value_1,value_2"
"SM_USER": "email@domain.com"
Einschränkungen bei der Verwendung der SAML-Attributweitergabe
Bei der Anmeldung gilt für eingehende Attribute vom Identitätsanbieter ein Limit von 2 KB an SAML-Attributdaten. Assertions, die das Maximum von 2 KB überschreiten, werden abgelehnt und die Anmeldung schlägt fehl.
Die meisten Webserver haben ein Limit von 8 KB für die Anfrageseite. 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
Diese Funktion unterstützt keine Unicode- und UTF-8-Zeichen. Attributwerte müssen daher Low-ASCII-Strings sein. Wenn eine Assertion nicht im niedrigen ASCII-Format vorliegt, schlägt die Anmeldung fehl.