Lint-Richtlinien

In diesem Abschnitt wird beschrieben, wie Sie Ihre IAM-Richtlinien (Identity and Access Management) mit Linting validieren.

Hinweis

Informationen zum Linting für IAM-Richtlinien

Im Rahmen von IAM-Richtlinien wird Linting als Methode eingesetzt, um neue oder bestehende Richtlinien auf bestimmte Probleme hin zu prüfen. Hierbei kann es sich beispielsweise um solche Probleme handeln:

  • Vorschläge
  • Warnungen
  • Informationen, die zur Verbesserung der Absicht der Richtlinie beitragen können, beispielsweise eine bessere Syntax und Semantik
  • Syntax- oder Semantikfehler, die dazu führen, dass setIamPolicy-Vorgänge fehlschlagen

Das Linting einer Richtlinie kann als Debugging-Tool verwendet werden, um eine detaillierte Erklärung für fehlgeschlagene setIamPolicy()-Vorgänge bereitzustellen. Es kann auch als Tool zum Erstellen einer IAM-Richtlinie verwendet werden, um das gewünschte Ergebnis zu erzielen.

Linting einer Bedingung

Bedingungsausdrücke können häufig komplex werden, insbesondere in Szenarien, in denen mehrere Klauseln und logische Operatoren erforderlich sind, um den Zugriff entsprechend einzuschränken. Wenn ein Bedingungsausdruck ungültige Logik enthält oder die Syntax gegen die Einschränkungen eines Bedingungsausdrucks verstößt, schlägt der Vorgang setIamPolicy() fehl. Darüber hinaus kann eine Bedingung zwar alle strengen Syntax- und Semantikanforderungen für die Richtlinienaktualisierung erfüllen, aber dennoch Konstrukte enthalten, die während der Durchsetzung der Richtlinie zu unerwarteten Zugriffsergebnissen führen können. Beispiele für solche Fälle:

  • Verwendung von nicht empfohlenen Funktionen
  • Verwendung von Legacy-Ressourcentypen oder Legacy-Dienstnamen
  • Unwirksame Bedingungen, z. B. ein ungültiger Datums- oder Zeitraum

Das Linting einer Bedingung führt eine gründliche Prüfung durch und meldet sowohl die Fehler, die bei der Aktualisierung von Richtlinien auftreten können als auch andere fragwürdige Konstrukte.

Bevor Sie eine neue bedingte Rollenbindung festlegen, sollten Sie den Ausdruck zuerst per Linting verknüpfen. In diesem Abschnitt erfahren Sie, wie Sie Linting für einen Bedingungsausdruck mit der Cloud Console, dem gcloud-Befehlszeilentool oder der REST API durchführen.

So führen Sie Linting für einen Bedingungsausdruck durch:

Console

  1. Rufen Sie in der Cloud Console die Seite IAM auf.

    Zur Seite "IAM"

  2. Klicken Sie auf Projekt auswählen, wählen Sie ein Projekt aus und klicken Sie auf Öffnen.

  3. Suchen Sie in der Mitgliederliste nach dem gewünschten Mitglied und klicken Sie auf die Schaltfläche .

  4. Suchen Sie im Bereich Berechtigungen bearbeiten die gewünschte Rolle, für die Sie Linting durchführen möchten. Klicken Sie dann unter Bedingung auf den Namen der Bedingung.

  5. Im Bereich Bedingung bearbeiten bietet der Bedingungseditor die Möglichkeit zum Linting des Ausdrucks. Der Builder für IAM-Bedingungen bietet derzeit eingeschränkte Linting-Funktionen.

  6. Fügen Sie im Bedingungseditor einen Bedingungsausdruck manuell hinzu oder bearbeiten Sie ihn.

  7. Prüfen Sie die CEL-Syntax. Klicken Sie dazu über dem Textfeld rechts oben auf Linter ausführen. Wenn die Syntax Fehler enthält, wird neben jeder Zeile des Ausdrucks ein -Symbol angezeigt. Wenn Sie den Mauszeiger auf das Symbol bewegen, wird die Fehlermeldung für diesen Teil des Ausdrucks sowie konkret umsetzbares Feedback zur Fehlerbehebung angezeigt.

    Wir empfehlen Ihnen, die Fehler zu beheben, bevor Sie die Bedingung speichern. Wenn die Syntax der Bedingungen korrekt ist, der Lint-Vorgang jedoch fragwürdige Konstrukte findet, wird ein Warnsymbol () angezeigt. Wenn Sie den Mauszeiger auf das Symbol bewegen, wird die Warnmeldung für diesen Teil des Ausdrucks sowie konkret umsetzbares Feedback zur Fehlerbehebung angezeigt. Es wird zwar dringend empfohlen, die Ursachen der Warnung zu beheben, bevor Sie die Bedingung speichern, jedoch ist dies nicht zwingend erforderlich.

  8. Nehmen Sie die erforderlichen Änderungen am Bedingungsausdruck vor. Nachdem Linter ausführen ausgeführt wird, läuft dieser weiter im Hintergrund, um die Bearbeitung des Ausdrucks zu erleichtern.

  9. Klicken Sie auf Speichern, nachdem Linting erfolgreich auf den Ausdruck ausgeführt wurde, um die Bedingung anzuwenden.

  10. Sobald der Bereich Bedingung bearbeiten geschlossen wurde, klicken Sie im Bereich Berechtigungen bearbeiten noch einmal auf Speichern, um die IAM-Richtlinie zu aktualisieren.

gcloud-Befehl

Wenden Sie Linting mit dem Befehl gcloud alpha iam policies lint-condition auf einen bestimmten Bedingungsausdruck an. Zur Ausführung dieses Befehls können Sie entweder eine Textdatei mit der Bedingung erstellen oder Flags für den Titel, die Beschreibung und den Ausdruck der Bedingung angeben.

Im folgenden Beispiel verwenden wir eine Textdatei, die die Bedingung enthält:

condition.json

"condition": {
    "title": "1_less_than_2",
    "description": "",
    "expression": "1 <"
}

Befehl:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Die Ausgabe des Befehls enthält Folgendes:

lintResults:
- debugMessage: |-
    ERROR: Parse expression:1:3: mismatched input '<EOF>' expecting {'[', '{', '(', '.', '-', '!', 'true', 'false', 'null', NUM_FLOAT, NUM_INT, NUM_UINT, STRING, BYTES, IDENTIFIER}
      | 1 >
      | ...^
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 3
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionCompileCheck
...

Jedes der Lint-Ergebnisse enthält eine debugMessage, die zum Auffinden des Problems mit dem Bedingungsausdruck verwendet werden kann. Wenn die Bedingung nicht kompiliert werden konnte, sehen Sie möglicherweise viele verschiedene validationUnitName-Typen mit dem folgenden debugMessage-Text:

The validation unit is skipped due to absence of a required object: CheckedExpr

Nehmen Sie alle erforderlichen Änderungen vor, damit der Ausdruck erfolgreich kompiliert wird, und versuchen Sie dann noch einmal, Linting für die Bedingung durchzuführen.

REST API

Mit der Methode iamPolicies.lintPolicy wird für einen Bedingungsausdruck in einer IAM-Richtlinie das Linting bzw. die Validierung durchgeführt.

Ersetzen Sie diese Werte in den folgenden Anweisungen:

  • condition: Ein Expr-Objekt, das die Bedingung darstellt, für die das Linting durchgeführt werden soll. Beispiel:

    "title": "1_less_than_2",
    "description": "",
    "expression": "1 <"
    
    Informationen zum Format eines Expr-Objekts finden Sie in der Expr-Schemareferenz.

HTTP-Methode und URL:

POST https://iam.googleapis.com/v1/iamPolicies:lintPolicy

JSON-Text anfordern:

{
  "condition": {
    condition
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Der Antworttext enthält ein oder mehrere LintResult-Objekte. Beispiel:

{
  "lint_results": {
    "level": "CONDITION",
    "validation_unit_name": "LintValidationUnits/ConditionCompileCheck",
    "severity": "ERROR",
    "field_name": "condition.expression",
    "location_offset": "2",
    "debug_message": "ERROR: Parse expression:1:2: mismatched input \'<EOF>\' expecting {\'[\', \'{\', \'(\', \'.\', \'-\', \'!\', \'true\', \'false\', \'null\', NUM_FLOAT, NUM_INT, NUM_UINT, STRING, BYTES, IDENTIFIER}\n  | 1<\n  | ..^"
  },
  "lint_results": {
    "level": "CONDITION",
    "validation_unit_name": "LintValidationUnits/ConditionComplexityCheck",
    "severity": "NOTICE",
    "field_name": "condition.expression",
    "debug_message": "The validation unit is skipped due to absence of a required object: CheckedExpr"
  }
}

Jedes der Lint-Ergebnisse enthält eine debug_message, die zum Auffinden des Problems mit dem Bedingungsausdruck verwendet werden kann. Wenn die Bedingung nicht kompiliert werden konnte, sehen Sie möglicherweise viele verschiedene validation_unit_name-Typen mit dem folgenden debugMessage-Text:

The validation unit is skipped due to absence of a required object: CheckedExpr

Nehmen Sie alle erforderlichen Änderungen vor, damit der Ausdruck erfolgreich kompiliert wird, und versuchen Sie dann noch einmal, Linting für die Bedingung durchzuführen.

Unterstützte Validierungseinheiten

Wie im obigen Abschnitt beschrieben, ist eine Validierungseinheit ein einzelner Lint-Typ, der den Ausdruck auf Syntaxprobleme hin auswertet. Die folgende Tabelle fasst die unterstützten Validierungseinheiten zusammen, jeweils mit der beabsichtigten Linting-Stufe, dem Schweregrad der Linting-Ergebnisse und einer kurzen Beschreibung.

Validierungseinheit Lint-Stufe Schweregrad Beschreibung
ConditionCompileCheck CONDITION ERROR Der Bedingungsausdruck enthält einen Kompilierungsfehler aufgrund einer ungültigen CEL-Syntax.
ConditionComplexityCheck CONDITION ERROR Der Bedingungsausdruck enthält mehr als die maximal 12 logischen Operatoren.
DateTimeCheck CONDITION WARNING Der Bedingungsausdruck gibt an, dass ein Zeitstempelvergleich aufgrund eines ungültigen Zeitstempelformats (nicht ISO 8601) effektiv wahr bzw. falsch ist oder der Ablaufzeitstempel bzw. Startzeitstempel in der Vergangenheit liegt.
DateTimeRangeCheck CONDITION WARNING Wert außerhalb des Bereichs für die vorgesehene erweiterte Zeitstempelfunktion und den Vergleichsausdruck. Hier finden Sie weitere Informationen zum gültigen Wertebereich für erweiterte Zeitstempelfunktionen.
EffectiveTimeRangeCheck CONDITION WARNING Bei einer komplexeren Verwendung von Zeitstempelfunktionen und Vergleichen führt der Ausdruck zu einem leeren effektiven Zeitraum und ist daher effektiv falsch. Alternativ deckt der Zeitraum einen vollständigen Bereich ab und ist daher effektiv wahr.
ResourceServiceLiteralCheck CONDITION WARNING Der angegebene Wert für resource.service wird nicht unterstützt. Der Ausdruck, der ein solches String-Literal für den Gleichheitsvergleich verwendet, ist effektiv falsch. Hier finden Sie weitere Informationen zu unterstützten Werten.
ResourceTypeLiteralCheck CONDITION WARNING Der angegebene Wert für resource.type wird nicht unterstützt. Der Ausdruck, der ein solches String-Literal für den Gleichheitsvergleich verwendet, ist effektiv falsch. Hier finden Sie weitere Informationen zu unterstützten Werten.
RestrictedAttributesCheck CONDITION WARNING Der Ausdruck verwendet ein Attribut, das derzeit eingeschränkt oder nicht unterstützt wird. Das Festlegen des Bedingungsausdrucks ist möglicherweise nicht erfolgreich. Hier finden Sie eine Liste der Attribute und die Release-Phasen.

Beispiele für Linting

In diesem Abschnitt finden Sie Beispiele für die Verwendung der Linting-Richtlinie für jede Validierungseinheit. Für jede Validierungseinheit wird die problematische Beispieleingabe bereitgestellt. In jedem Beispiel wird Linting mit dem gcloud-Befehlszeilentool veranschaulicht

ConditionCompileCheck

Beispiel für einen Bedingungsausdruck:

{
    "condition": {
      "title": "Condition not compiling",
      "description": "",
      "expression":
        "true=false"
    }
}

Befehl ausführen:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Lint-Ergebnis:

lintResults:
- debugMessage: |-
    ERROR: Parse expression:1:4: token recognition error at: '=f'
      | true=false
      | ....^
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 4
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionCompileCheck

ConditionComplexityCheck

Beispiel für einen Bedingungsausdruck:

{
    "condition": {
      "title": "Condition not compiling",
      "description": "",
      "expression":
        "1<2 || 2<3 || 3<4 || 4<5 || 5<6 || 6<7 || 7<8 || 8<9 || 9<10 || 10<11
        || 11<12 || 12<13 || 13<14 || 14<15"
    }
}

Befehl ausführen:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Lint-Ergebnis:

lintResults:
- debugMessage: Logical operators count must not be more than 12
  fieldName: condition.expression
  level: CONDITION
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionComplexityCheck

DateTimeCheck

Beispiel für einen Bedingungsausdruck:

{
    "condition": {
      "title": "Condition not compiling",
      "description": "",
      "expression": "request.time < timestamp('2000-01-01T00:00:00Z')"
    }
}

Befehl ausführen:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Lint-Ergebnis:

lintResults:
- debugMessage: Ineffective date time value 2000-01-01T00:00:00+00:00 parsed from
    "2000-01-01T00:00:00Z"; condition is effectively False. Time expired already.
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 25
  severity: WARNING
  validationUnitName: LintValidationUnits/DateTimeCheck

DateTimeRangeCheck

Beispiel für einen Bedingungsausdruck:

{
    "condition": {
      "title": "Time function out of range",
      "description": "",
      "expression":
        "request.time.getMonth() > 13"
    }
}

Befehl ausführen:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Lint-Ergebnis:

lintResults:
- debugMessage: The value being compared to the specified timestamp function (getMonth)
    must be in range [0, 11].
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 26
  severity: WARNING
  validationUnitName: LintValidationUnits/DateTimeRangeCheck

EffectiveTimeRangeCheck

Beispiel für einen Bedingungsausdruck:

{
    "condition": {
      "title": "Empty time range",
      "description": "",
      "expression":
        "request.time.getMonth() > 5 && request.time.getMonth() < 4"
    }
}

Befehl ausführen:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Lint-Ergebnis:

lintResults:
- debugMessage: The aggregate of time functions [getMonth] results in empty ranges.
  fieldName: condition.expression
  level: CONDITION
  severity: WARNING
  validationUnitName: LintValidationUnits/EffectiveTimeRangeCheck

ResourceServiceLiteralCheck

Beispiel für einen Bedingungsausdruck:

{
    "condition": {
      "title": "Condition with unsupported resource service string",
      "description": "",
      "expression":
        "resource.service == 'resourcemanager'"
    }
}

Befehl ausführen:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Lint-Ergebnis:

lintResults:
- debugMessage: 'resource.service : resourcemanager is not supported. Using this
    value in condition may lead to unintended consequences. Check user guide at
    https://cloud.google.com/iam/docs/conditions-resource-attributes#resource_service_values
    for supported values for resource.service.'
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 20
  severity: WARNING
  validationUnitName: LintValidationUnits/ResourceServiceLiteralCheck

ResourceTypeLiteralCheck

Beispiel für einen Bedingungsausdruck:

{
    "condition": {
      "title": "Condition with legacy resource type",
      "description": "",
      "expression":
        "resource.type == 'resourcemanager.projects'"
    }
}

Befehl ausführen:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Lint-Ergebnis:

lintResults:
- debugMessage: 'resource.type : resourcemanager.projects is not supported.
    Using this value in condition may lead to unintended consequences. Check
    user guide at https://cloud.google.com/iam/docs/conditions-resource-attributes#resource_type_values
    for supported values for resource.type.'
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 17
  severity: WARNING
  validationUnitName: LintValidationUnits/ResourceTypeLiteralCheck

RestrictedAttributesCheck

Beispiel für einen Bedingungsausdruck:

{
    "condition": {
      "title": "Condition with restricted attribute",
      "description": "",
      "expression":
        "'accessPolicies/123/accesslevels/TRUSTED' in request.auth.access_levels"
    }
}

Befehl ausführen:

gcloud alpha iam policies lint-condition --condition-from-file=`condition.json`

Lint-Ergebnis:

lintResults:
- debugMessage: Condition attribute `request.auth.access_levels` is in private beta
    release and may be subject to whitelist control. Please check https://cloud.google.com/iam/docs/conditions-overview
    for the full list of restricted attributes
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 57
  severity: WARNING
  validationUnitName: LintValidationUnits/RestrictedAttributesCheck