SAML-Attributweitergabe konfigurieren

Auf dieser Seite wird beschrieben, wie Sie die Attributweitergabe für Security Assertion Markup Language (SAML) 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.

Hinweis: Die Weitergabe von SAML-Attributen wird für Google-Identitäten unterstützt, die die Einmalanmeldung (SSO) mit einem externen SAML-Identitätsanbieter in Google Workspace oder Cloud Identity verwenden. Die Weitergabe von SAML-Attributen wird für Anwendungen, die für die Verwendung von IAP mit der Workforce Identity-Föderation konfiguriert sind, nicht unterstützt.

Hinweis

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

Umgang mit den Daten

Bevor Sie die SAML-Attributweitergabe aktivieren, sollten Sie sich darüber informieren, 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 die Informationen aufgenommen werden, die es Ihren geschützten Anwendungen zur Verfügung stellt. Wenn Sie die Einmalanmeldung (SSO) über einen externen Identitätsanbieter eingerichtet haben und Ihr Identitätsanbieter ein <AttributeStatement> in die SAML-Assertion einfügt, speichertGoogle Cloud vorübergehend die Attribute, die mit der Google-Kontositzung eines Nutzers verknüpft sind. 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 (PII), wie Kontoanmeldedaten, amtliche Ausweisnummern, Karteninhaberdaten, Kontodaten, Gesundheitsdaten oder vertrauliche Hintergrundinformationen.

SAML-Attributweitergabe aktivieren

Aktivieren Sie die Weitergabe von SAML-Attributen, indem Sie ein SSO-Profil in Google Workspace erstellen, und aktualisieren Sie dann die IAP-Einstellungen mithilfe der Google Cloud CLI oder der REST API.

Hinweis: Wenn Sie diese Funktion für bestimmte Nutzer oder Nutzergruppen aktivieren, wird Ihre vorhandene SAML-Konfiguration überschrieben.

Console

1. Rufen Sie in der Google Cloud Console die IAP-Seite auf.
   Zu IAP
2. Öffnen Sie die Einstellungen für eine Ressource und scrollen Sie zu Attributweitergabe.
3. Wählen Sie Attributweitergabe aktivieren aus und klicken Sie auf Speichern.

4. Geben Sie auf dem Tab SAML-Attribute die Attribute ein, die Sie im folgenden Format weitergeben möchten: attribute1, attribute2, attribute3

   Sie können die Attribute auch mithilfe eines benutzerdefinierten Ausdrucks 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'])

5. Wählen Sie unter Zu übergebende Anmeldedatentypen mindestens ein Attributformat aus, das vom IdP bereitgestellt und an Anwendungen übergeben werden soll.

gcloud

Führen Sie die folgenden gcloud CLI-Befehle für IAP 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 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 zu übertragenden SAML-Attribute 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
}

Anmeldedaten für die Ausgabe festlegen

Wenn Sie die SAML-Attributweitergabe verwenden, können Sie Attribute über mehrere Medien senden, einschließlich JSON Web Token (JWT) und Header, indem Sie Ausgabeanmeldedaten festlegen. Wenn Sie die Anmeldedaten in der API festlegen möchten, können Sie eine Liste mit kommagetrennten 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.

Für die Verwendung von CEL-Ausdrücken mit der SAML-Attributweitergabe gelten die 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 IAP-SAML-Attributweitergabe unterstützt werden.

Bei den Funktionen wird zwischen Groß- und Kleinschreibung unterschieden. Sie müssen genau wie angegeben 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 ein String sein.
Filterlisten	list.Filter(iter_var, condition)	Gibt eine Teilmenge von list zurück, bei der die Elemente condition erfüllen.
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, bei dem name = "name".
append	list.append(attribute)	Hängt 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 wird.
emitAs	attribute.emitAs("new_name")	Gibt das angegebene Attribut mit dem Namen "new_name" an alle ausgewählten Ausgabe-Anmeldedaten aus.

Beispiel für einen CEL-Ausdruck

Angenommen, es gibt 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 Ausgabe-Anmeldedaten vollständig dupliziert.

Beispiel: 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 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 mit URL-Escaping versehen und durch Kommas verbunden. 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 die von der Anwendung 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 wird gezeigt, wie IAP Sonderzeichen maskiert, 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"

Im Folgenden finden Sie ein Beispiel dafür, 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 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 keine SAML-Attributweitergabe benötigen, 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 der Liste iap_attributes auswählen: attributes.iap_attributes…

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 können.

Nehmen Sie die Beispiel-SAML-Assertion an.

selectByName

Mit der Funktion selectByName können Sie ein einzelnes Attribut aus einer bestimmten Liste nach Name 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 ein Attribut an eine Liste von Attributen anhä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 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" zur Filterliste hinzufügen. Sie können auch mehrere Attribute hinzufügen und sie an eine Liste anhängen, indem Sie die Anhänge 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 Anhängen einzelner Attribute ist am nützlichsten, wenn es mit den Funktionen strict und emitAs kombiniert wird.

strict

Verwenden Sie die Funktion strict, um ein Attribut zu kennzeichnen, damit IAP dem Namen nicht x-goog-iap-attr- voranstellt. Dies 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

Verwenden Sie die Funktion emitAs, um einen neuen Namen für das Attribut anzugeben. 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. Sie können beispielsweise den folgenden Ausdruck verwenden, um die E-Mail-Adresse eines Nutzers aus IAP-Attributen als "SM_USER" zusammen mit anderen SAML-Attributen weiterzugeben:

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": "[e-mail]"

Einschränkungen bei der Verwendung der SAML-Attributweitergabe

Bei der Anmeldung sind eingehende Attribute vom Identitätsanbieter auf 2 KB 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 ein Limit von 8 KB für die Anfragegröß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) nach dem Duplizieren und Codieren 5.000 Byte überschreitet, lehnt IAP die Anfrage ab und gibt den IAP-Fehlercode 401 zurück.

Unicode-Zeichen in der SAML-Attributweitergabe

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.