Diese Seite wurde von der Cloud Translation API übersetzt.

SAML-Attributweitergabe konfigurieren

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 gesendet werden sollen.

Hinweise

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

Umgang mit den Daten

Bevor Sie die SAML-Attributweitergabe aktivieren, sollten Sie wissen, wie die Daten inGoogle Cloud verwaltet werden und welche Art von Informationen Sie über diesen Kanal senden 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 eine <AttributeStatement> in der SAML-Assertion enthält, 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 Vorgang 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 in Google Workspace ein SSO-Profil erstellen. Aktualisieren Sie dann die IAP-Einstellungen mit der Google Cloud CLI oder der REST API.

Console

Rufen Sie in der Google Cloud -Konsole die Seite „IAP“ auf.
Zu IAP
Öffnen Sie die Einstellungen für eine Ressource und scrollen Sie zu Attributübertragung.
Wählen Sie Attributübertragung aktivieren aus und klicken Sie 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. 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 Überzugebende Anmeldedatentypen mindestens ein Attributformat aus, das vom IdP an Anwendungen übergeben werden soll.

gcloud

Führen Sie die folgenden IAP-Befehle für die gcloud CLI 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 mithilfe des Objekts ApplicationSettings in IapSettings so konfigurieren, dass sie weitergegeben werden, 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 Headern. Dazu müssen Sie Ausgabeanmeldedaten festlegen. Um die Anmeldedaten in der API festzulegen, können Sie eine Liste von durch Kommas getrennten Strings angeben, wie im folgenden Beispiel gezeigt:

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

SAML-Attribute mit Common Expression Language filtern

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

Die Verwendung von CEL-Ausdrücken mit SAML-Attributweitergabe hat die folgenden Einschränkungen:

Ein Ausdruck muss eine Liste von Attributen zurückgeben.
Mit einem Ausdruck können maximal 45 Attribute ausgewählt werden.
Ein Ausdrucksstring darf 1.000 Zeichen nicht überschreiten.

Im Folgenden finden Sie die CEL-Funktionen, die bei Verwendung der IAP-Funktion zur SAML-Attributweitergabe unterstützt werden.

Bei den Funktionen wird die Groß- und Kleinschreibung berücksichtigt. Sie müssen genau so verwendet werden, wie sie geschrieben sind. Die Reihenfolge der Funktionen strict und emitAs spielt keine Rolle, wenn Funktionsaufrufe verschachtelt werden.

Funktion	Beispiel	Beschreibung
Feldauswahl	`a.b`	Wählen Sie im Proto `a` das Feld `b` 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, bei der die Elemente `condition` erfüllen.
Mitgliedschaft auflisten	„`a`“ in „`b`“	Gibt `true` zurück, wenn der Wert `a` Mitglied der Liste `b` ist.
selectByName	`list.selectByName("name")`	Wählen Sie in der Liste das Attribut aus, für das `name = "name"` gilt.
Anfügen	`list.append(attribute)`	Hängt das angegebene Attribut an die angegebene Liste an.
streng	`attribute.strict()`	Das Attribut wird ohne das Präfix `x-goog-iap-attr-` gesendet, wenn `HEADERS` als Ausgabe-Anmeldedaten verwendet wird.
emitAs	`attribute.emitAs("new_name")`	Gibt das angegebene Attribut mit dem Namen `"new_name"` für alle ausgewählten Ausgabeanmeldedaten aus.

Beispiel-CEL-Ausdruck

Angenommen, 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"])

Wenn Sie my_saml_attr_1 und my_saml_attr_2 auswählen möchten, verwenden Sie den folgenden CEL-Ausdruck:

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: 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

Die Attribute werden über das Feld additional_claims im JWT-Token bereitgestellt. Das Feld ist ein Objekt und enthält eine Zuordnung der Attributnamen zu einer Liste der Attributwerte. Die Attributnamen entsprechen denen in den bereitgestellten SAML-Behauptungen.

In der 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-entkommentiert und durch Kommas getrennt. 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. So wird sichergestellt, dass Header, die von der App empfangen werden, von IAP generiert werden.

Bei der 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 spezielle Zeichen bei der Weiterleitung von Attributen in Headern wie value&1, value$2 und value,3 entkommt:

"x-goog-iap-attr-my_saml_attr_1": "value%261,value%242,value%2C3"

Im folgenden Beispiel wird gezeigt, wie ein Headername entkommentiert wird.

Header name:

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

Escaped-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 unter iap_attributes list: attributes.iap_attributes…

IAP bietet die folgenden Attribute: user_email, device_id und timestamp.

Beispiele

In den folgenden Beispielen wird gezeigt, wie Sie Attribute mithilfe der Funktionen selectByName, append, strict und emitas anpassen.

Angenommen, es geht um 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 anhängen. 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 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"))

Sie können "my_saml_attr_2" der Filterliste hinzufügen. Sie können auch mehrere Attribute hinzufügen und einer Liste anhängen, indem Sie die Anhänge verketten, z. B. so:

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 kein Präfix x-goog-iap-attr- vorangestellt. Das ist nützlich, wenn ein Attributname für die Backend-Anwendung genau festgelegt werden 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")

Mit den verschiedenen Funktionen können Sie Attribute für bestimmte Anwendungsfälle anpassen. Mit dem folgenden Ausdruck kannst du 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 SAML-Attributweitergabe

Bei der Anmeldung ist die Größe der SAML-Attributdaten von eingehenden Attributen vom Identitätsanbieter auf 2 KB begrenzt. 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 Anfragegröße. Dadurch wird die Größe der ausgehenden benutzerdefinierten Attribute begrenzt, einschließlich duplizierter Attribute 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 bei der SAML-Attributweitergabe

Diese Funktion unterstützt keine Unicode- und UTF-8-Zeichen. Daher müssen Attributwerte niedrige ASCII-Strings sein. Wenn eine Assertion nicht im niedrigen ASCII-Format vorliegt, schlägt die Anmeldung fehl.