Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

SAML-Attributweitergabe konfigurieren

Auf dieser Seite wird beschrieben, wie Sie die Weitergabe von SAML-Attributen (Security Assertion Markup Language) aktivieren und verwenden. Mit dieser Funktion können Sie SAML-Attribute von einem Identitätsanbieter an Anwendungen weitergeben, die durch den 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.

Hinweis

Sie sollten mit der Spezifikation für SAML V2.0-Assertions und -Protokolle (PDF) vertraut sein.

Umgang mit Daten

Bevor Sie die Weitergabe von SAML-Attributen aktivieren, sollten Sie wissen, wie Google Cloud mit den Daten umgeht und welche Arten 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 an Ihre geschützten Anwendungen weitergegeben werden. Wenn Sie die Einmalanmeldung (SSO) über einen externen Identitätsanbieter einrichten und Ihr Identitätsanbieter ein <AttributeStatement> in die SAML-Assertion einfügt, Google Cloud speichert die Attribute, die mit der Google-Kontositzung eines Nutzers verknüpft 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 Weitergabe von SAML-Attributen nicht für vertrauliche personenidentifizierbare Informationen wie Anmeldedaten für Konten, behördliche Identifikationsnummern, Karteninhaberdaten, Finanzdaten, 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 und dann die IAP-Einstellungen mit der Google Cloud CLI oder der REST API aktualisieren.

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-Attribute die Attribute ein, die Sie weitergeben möchten, und verwenden Sie dabei das folgende Format: attribute1, attribute2, attribute3

Sie können die Attribute auch mit einem benutzerdefinierten Ausdruck eingeben.Die Attribute für Ihren benutzerdefinierten Ausdruck werden auf dem Tab SAML-Attribute angezeigt. Damit Ihre Attribute auf dem Tab SAML-Attribute angezeigt werden, müssen Sie das folgende Ausdrucksformat verwenden:
attributes.saml_attributes.filter(attribute, attribute.name in ['attribute', 'attribute2', 'attribute1'])
Wählen Sie unter Anmeldedatentypen, die weitergegeben werden sollen mindestens ein Attributformat aus, das vom IdP stammt und an Anwendungen weitergegeben werden soll.

gcloud

Führen Sie die folgenden IAP-gcloud CLI-Befehle 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: ORDNER: Der Ordner, in dem sich Ihre Anwendung befindet.
ORGANIZATION: ORGANISATION: 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 weiterzugebenden SAML-Attribute mit dem ApplicationSettings Objekt 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 Weitergabe von SAML-Attributen verwenden, können Sie Attribute über mehrere Medien senden, einschließlich JSON Web Token (JWT) und Headern, indem Sie Ausgabeanmeldedaten festlegen. Wenn Sie die Anmeldedaten in der API festlegen möchten, können Sie eine Liste kommagetrennter Strings angeben, wie im folgenden Beispiel gezeigt:

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

SAML-Attribute mit der Common Expression Language filtern

Sie können SAML-Attribute mit Funktionen der Common Expression Language (CEL) filtern.

Bei der Verwendung von CEL-Ausdrücken mit der Weitergabe von SAML-Attributen gelten die folgenden Einschränkungen:

Ein Ausdruck muss eine Liste von Attributen zurückgeben.
Ein Ausdruck kann maximal 45 Attribute auswählen.
Ein Ausdrucksstring darf 1.000 Zeichen nicht überschreiten.

Im Folgenden sind die CEL-Funktionen aufgeführt, die bei der Verwendung der Funktion zur Weitergabe von SAML-Attributen in IAP unterstützt werden.

Bei den Funktionen wird zwischen Groß- und Kleinschreibung unterschieden. Sie müssen genau so verwendet werden, wie sie geschrieben sind. Die Reihenfolge der Funktionen strict und emitAs spielt bei der Verkettung von Funktionsaufrufen keine Rolle.

Funktion	Beispiel	Beschreibung
Feldauswahl	`a.b`	Wählt 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, in der die Elemente die `condition` erfüllen.
Listenmitgliedschaft	`a` in `b`	Gibt `true` zurück, wenn der Wert `a` ein Mitglied der Liste `b` ist.
selectByName	`list.selectByName("name")`	Wählt aus der Liste das Attribut aus, bei dem `name = "name"` gilt.
append	`list.append(attribute)`	Fügt das angegebene Attribut an die angegebene Liste an.
strict	`attribute.strict()`	Gibt das Attribut ohne das Präfix `x-goog-iap-attr-` aus, wenn `HEADERS` als Ausgabeanmeldedaten verwendet werden.
emitAs	`attribute.emitAs("new_name")`	Gibt das angegebene Attribut mit dem Namen `"new_name"` an alle ausgewählten Ausgabeanmeldedaten 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 Ausgabeanmeldedaten vollständig dupliziert.

Beispiel: 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: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 bleiben 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. Beispiel: header&name: header$value wird zu x-goog-iap-attr-header%26name: header%24value.

Um IAP-Header eindeutig zu identifizieren, 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"

Das folgende Beispiel zeigt, wie IAP Sonderzeichen codiert, wenn Attribute in Headern weitergegeben werden, z. B. value&1, value$2, und value,3:

"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 codiert wird.

Header name:

"iap,test,3": "iap_test3_value1,iap_test3_value2"

Codierter 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 Namen der weitergegebenen Attribute ändern, angeben, ob das Headerpräfix für einige Attribute verwendet werden soll, und neue von IAP bereitgestellte Attribute auswählen.

Wenn Sie die Weitergabe von SAML-Attributen nicht 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 aus der iap_attributes list auswählen: attributes.iap_attributes…

IAP stellt die folgenden Attribute bereit: user_email, device_id und timestamp.

Beispiele

Die folgenden Beispiele zeigen, wie Sie Attribute mit den Funktionen selectByName, append, strict und emitas anpassen.

Angenommen, Sie haben die Beispiel-SAML-Assertion.

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 IAP-Attributlisten 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 "my_saml_attr_2" der Filterliste 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 für 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 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 Verwendung der Weitergabe von SAML-Attributen

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 Anfragengröße. 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 niedrige ASCII-Strings sein. Wenn eine Assertion nicht im niedrigen ASCII-Format vorliegt, schlägt die Anmeldung fehl.