Anwendung mit signierten Headern schützen

Auf dieser Seite wird gezeigt, wie Sie Ihre Anwendung mit signierten IAP-Headern schützen können. Bei entsprechender Konfiguration sorgt Identity-Aware Proxy (IAP) mit JSON-Web-Tokens (JWTs) dafür, dass eine Anfrage an Ihre Anwendung autorisiert ist. Dies schützt Ihre Anwendung vor folgenden Risiken:

  • IAP wurde versehentlich deaktiviert;
  • falsch konfigurierte Firewalls;
  • Zugriffe aus dem Projekt

Für eine ordnungsgemäße Sicherung der Anwendung müssen Sie für alle Anwendungstypen signierte Header verwenden.

Wenn Sie mit einer App Engine-Standardumgebung arbeiten, können Sie auch die User API verwenden.

Beachten Sie, dass die Compute Engine- und GKE-Systemdiagnosen keine JWT-Header verwenden und IAP keine Systemdiagnosen verarbeitet. Wenn bei der Systemdiagnose Zugriffsfehler zurückgegeben werden, müssen Sie prüfen, ob sie in der Cloud Console korrekt konfiguriert wurde und ob der Pfad der Systemdiagnose für die Validierung der JWT-Header auf die Zulassungsliste gesetzt wurde. Weitere Informationen finden Sie unter Ausnahme für Systemdiagnose erstellen.

Hinweis

Um Ihre Anwendung mit signierten Headern zu schützen, muss Folgendes vorhanden sein:

Anwendung mit IAP-Headern schützen

Für den Schutz Ihrer Anwendung mit dem IAP-JWT müssen Sie den Header, die Nutzlast und die Signatur des JWT prüfen. Das JWT befindet sich im HTTP-Anfrage-Header x-goog-iap-jwt-assertion. Wenn ein Angreifer IAP umgeht, kann er die nicht signierten IAP-Identitäts-Header x-goog-authenticated-user-{email,id} fälschen. Das IAP-JWT stellt dazu eine sicherere Alternative dar.

Signierte Header bieten eine sekundäre Sicherheit, wenn jemand IAP umgeht. Wenn IAP aktiviert ist, werden die vom Client bereitgestellten x-goog-*-Header entfernt, wenn die Anfrage über die IAP-Bereitstellungsinfrastruktur ausgeführt wird.

JWT-Header prüfen

Prüfen Sie, ob der Header des JWT den folgenden Anforderungen genügt:

Anforderungen an den JWT-Header
alg Algorithmus ES256
kid Schlüssel-ID Muss einem der öffentlichen Schlüssel entsprechen, die in der IAP-Schlüsseldatei aufgeführt und in zwei verschiedenen Formaten verfügbar sind: https://www.gstatic.com/iap/verify/public_key und https://www.gstatic.com/iap/verify/public_key-jwk.

Prüfen Sie, ob das JWT mit dem privaten Schlüssel signiert wurde, der der Anforderung kid des Tokens entspricht. Rufen Sie dazu zuerst den öffentlichen Schlüssel von einem der beiden folgenden URLs ab:

  • https://www.gstatic.com/iap/verify/public_key. Diese URL enthält ein JSON-Wörterbuch, das die kid-Anforderungen den öffentlichen Schlüsselwerten zuordnet.
  • https://www.gstatic.com/iap/verify/public_key-jwk. Diese URL enthält die öffentlichen IAP-Schlüssel im Format JWK.

Wenn der öffentliche Schlüssel verfügbar ist, prüfen Sie die Signatur mithilfe einer JWT-Bibliothek.

JWT-Nutzlast prüfen

Prüfen Sie, ob die Nutzlast des JWT den folgenden Anforderungen genügt:

Anforderungen an die JWT-Nutzlast
exp Ablaufzeit Muss in der Zukunft liegen. Die Zeit wird in Sekunden seit der UNIX-Epoche gemessen. Rechnen Sie rund 30 Sekunden Verzögerung ein. Die maximale Lebensdauer eines Tokens beträgt 10 Minuten + 2 * Verzögerung.
iat Ausstellungszeit Muss in der Vergangenheit liegen.j Die Zeit wird in Sekunden seit der UNIX-Epoche gemessen. Rechnen Sie rund 30 Sekunden Verzögerung ein.
aud Zielgruppe Muss ein String mit folgenden Werten sein:
  • App Engine: /projects/PROJECT_NUMBER/apps/PROJECT_ID
  • Compute Engine und GKE: /projects/PROJECT_NUMBER/global/backendServices/SERVICE_ID
iss Aussteller Muss https://cloud.google.com/iap lauten.
hd Kontodomain Wenn ein Konto zu einer gehosteten Domain gehört, wird die Anforderung hd bereitgestellt, um die Domain, der das Konto zugeordnet ist, identifizieren zu können.
google Google-Anforderung Wenn für die Anfrage eine oder mehrere Zugriffsebenen gelten, werden deren Namen im JSON-Objekt der google-Anforderung unter dem Schlüssel access_levels als Stringarray gespeichert.

Sie können die oben genannten Werte für den String aud mithilfe der Cloud Console oder des gcloud-Befehlszeilentools abrufen.

Zum Abrufen der aud-Stringwerte in der Cloud Console öffnen Sie die Identity-Aware Proxy-Einstellungen für Ihr Projekt und klicken neben der Load-Balancer-Ressource auf das Dreipunkt-Menü. Wählen Sie dann Signed Header JWT Audience (Zielgruppe für JWT mit signiertem Header) aus. Im anschließend eingeblendeten Dialogfeld JWT mit signiertem Header wird die aud-Anforderung für die ausgewählte Ressource angezeigt.

Dreipunkt-Menü mit der Option

Wenn Sie die aud Stringwerte mit dem gcloud-Befehlszeilentool des Cloud SDK abrufen möchten, müssen Sie die Projekt-ID kennen. Sie finden die Projekt-ID auf der Karte Projektinformationen der Cloud Console. Führen Sie dann die angegebenen Befehle für jeden Wert aus.

Projektnummer

Um mit dem gcloud-Befehlszeilentool die Projekt-ID abzurufen, führen Sie den folgenden Befehl aus:

gcloud projects describe PROJECT_ID

Der Befehl gibt in etwa Folgendes zurück:

createTime: '2016-10-13T16:44:28.170Z'
lifecycleState: ACTIVE
name: project_name
parent:
  id: '433637338589'
  type: organization
projectId: PROJECT_ID
projectNumber: 'PROJECT_NUMBER'

Dienst-ID

Um mit dem gcloud-Befehlszeilentool die Dienst-ID abzurufen, führen Sie den folgenden Befehl aus:

gcloud compute backend-services describe SERVICE_NAME --project=PROJECT_ID --global

Der Befehl gibt in etwa Folgendes zurück:

affinityCookieTtlSec: 0
backends:
- balancingMode: UTILIZATION
  capacityScaler: 1.0
  group: https://www.googleapis.com/compute/v1/projects/project_name/regions/us-central1/instanceGroups/my-group
connectionDraining:
  drainingTimeoutSec: 0
creationTimestamp: '2017-04-03T14:01:35.687-07:00'
description: ''
enableCDN: false
fingerprint: zaOnO4k56Cw=
healthChecks:
- https://www.googleapis.com/compute/v1/projects/project_name/global/httpsHealthChecks/my-hc
id: 'SERVICE_ID'
kind: compute#backendService
loadBalancingScheme: EXTERNAL
name: my-service
port: 8443
portName: https
protocol: HTTPS
selfLink: https://www.googleapis.com/compute/v1/projects/project_name/global/backendServices/my-service
sessionAffinity: NONE
timeoutSec: 3610

Nutzeridentität abrufen

Wenn die oben genannten Prüfungen erfolgreich abgeschlossen wurden, rufen Sie die Nutzeridentität ab. Die Nutzlast des ID-Tokens enthält folgende Nutzerinformationen:

Nutzeridentität in der Nutzlast des ID-Tokens
sub Betreff Die eindeutige, stabile Kennung für den Nutzer. Verwenden Sie diesen Wert anstelle des Headers x-goog-authenticated-user-id.
email E-Mail-Adresse des Nutzers Die E-Mail-Adresse des Nutzers.
  • Verwenden Sie diesen Wert anstelle des Headers x-goog-authenticated-user-email.
  • Im Gegensatz zu diesem Header und zur sub-Anforderung hat dieser Wert kein Namespace-Präfix.

Mit dem folgenden Beispielcode wird eine Anwendung mit signierten IAP-Headern geschützt:

C#


using Google.Apis.Auth;
using System;
using System.Threading;
using System.Threading.Tasks;

public class IAPTokenVerification
{
    /// <summary>
    /// Verifies a signed jwt token and returns its payload.
    /// </summary>
    /// <param name="signedJwt">The token to verify.</param>
    /// <param name="expectedAudience">The audience that the token should be meant for.
    /// Validation will fail if that's not the case.</param>
    /// <param name="cancellationToken">The cancellation token to propagate cancellation requests.</param>
    /// <returns>A task that when completed will have as its result the payload of the verified token.</returns>
    /// <exception cref="InvalidJwtException">If verification failed. The message of the exception will contain
    /// information as to why the token failed.</exception>
    public async Task<JsonWebSignature.Payload> VerifyTokenAsync(
        string signedJwt, string expectedAudience, CancellationToken cancellationToken = default)
    {
        SignedTokenVerificationOptions options = new SignedTokenVerificationOptions
        {
            // Use clock tolerance to account for possible clock differences
            // between the issuer and the verifier.
            IssuedAtClockTolerance = TimeSpan.FromMinutes(1),
            ExpiryClockTolerance = TimeSpan.FromMinutes(1),
            TrustedAudiences = { expectedAudience }
        };

        return await JsonWebSignature.VerifySignedTokenAsync(signedJwt, options, cancellationToken: cancellationToken);
    }
}

Go

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/api/idtoken"
)

// validateJWTFromAppEngine validates a JWT found in the
// "x-goog-iap-jwt-assertion" header.
func validateJWTFromAppEngine(w io.Writer, iapJWT, projectNumber, projectID string) error {
	// iapJWT := "YmFzZQ==.ZW5jb2RlZA==.and0" // req.Header.Get("X-Goog-IAP-JWT-Assertion")
	// projectNumber := "123456789"
	// projectID := "your-project-id"
	ctx := context.Background()
	aud := fmt.Sprintf("/projects/%s/apps/%s", projectNumber, projectID)

	payload, err := idtoken.Validate(ctx, iapJWT, aud)
	if err != nil {
		return fmt.Errorf("idtoken.Validate: %v", err)
	}

	// payload contains the JWT claims for further inspection or validation
	fmt.Fprintf(w, "payload: %v", payload)

	return nil
}

// validateJWTFromComputeEngine validates a JWT found in the
// "x-goog-iap-jwt-assertion" header.
func validateJWTFromComputeEngine(w io.Writer, iapJWT, projectNumber, backendServiceID string) error {
	// iapJWT := "YmFzZQ==.ZW5jb2RlZA==.and0" // req.Header.Get("X-Goog-IAP-JWT-Assertion")
	// projectNumber := "123456789"
	// backendServiceID := "backend-service-id"
	ctx := context.Background()
	aud := fmt.Sprintf("/projects/%s/global/backendServices/%s", projectNumber, backendServiceID)

	payload, err := idtoken.Validate(ctx, iapJWT, aud)
	if err != nil {
		return fmt.Errorf("idtoken.Validate: %v", err)
	}

	// payload contains the JWT claims for further inspection or validation
	fmt.Fprintf(w, "payload: %v", payload)

	return nil
}

Java


import com.google.api.client.http.HttpRequest;
import com.google.api.client.json.webtoken.JsonWebToken;
import com.google.auth.oauth2.TokenVerifier;

/** Verify IAP authorization JWT token in incoming request. */
public class VerifyIapRequestHeader {

  private static final String IAP_ISSUER_URL = "https://cloud.google.com/iap";

  // Verify jwt tokens addressed to IAP protected resources on App Engine.
  // The project *number* for your Google Cloud project via 'gcloud projects describe $PROJECT_ID'
  // The project *number* can also be retrieved from the Project Info card in Cloud Console.
  // projectId is The project *ID* for your Google Cloud Project.
  boolean verifyJwtForAppEngine(HttpRequest request, long projectNumber, String projectId)
      throws Exception {
    // Check for iap jwt header in incoming request
    String jwt = request.getHeaders().getFirstHeaderStringValue("x-goog-iap-jwt-assertion");
    if (jwt == null) {
      return false;
    }
    return verifyJwt(
        jwt,
        String.format("/projects/%s/apps/%s", Long.toUnsignedString(projectNumber), projectId));
  }

  boolean verifyJwtForComputeEngine(
      HttpRequest request, long projectNumber, long backendServiceId) throws Exception {
    // Check for iap jwt header in incoming request
    String jwtToken = request.getHeaders()
        .getFirstHeaderStringValue("x-goog-iap-jwt-assertion");
    if (jwtToken == null) {
      return false;
    }
    return verifyJwt(
        jwtToken,
        String.format(
            "/projects/%s/global/backendServices/%s",
            Long.toUnsignedString(projectNumber), Long.toUnsignedString(backendServiceId)));
  }

  private boolean verifyJwt(String jwtToken, String expectedAudience) {
    TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
        .setAudience(expectedAudience)
        .setIssuer(IAP_ISSUER_URL)
        .build();
    try {
      JsonWebToken jsonWebToken = tokenVerifier.verify(jwtToken);

      // Verify that the token contain subject and email claims
      JsonWebToken.Payload payload = jsonWebToken.getPayload();
      return payload.getSubject() != null && payload.get("email") != null;
    } catch (TokenVerifier.VerificationException e) {
      System.out.println(e.getMessage());
      return false;
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const iapJwt = 'SOME_ID_TOKEN'; // JWT from the "x-goog-iap-jwt-assertion" header

let expectedAudience = null;
if (projectNumber && projectId) {
  // Expected Audience for App Engine.
  expectedAudience = `/projects/${projectNumber}/apps/${projectId}`;
} else if (projectNumber && backendServiceId) {
  // Expected Audience for Compute Engine
  expectedAudience = `/projects/${projectNumber}/global/backendServices/${backendServiceId}`;
}

const oAuth2Client = new OAuth2Client();

async function verify() {
  // Verify the id_token, and access the claims.
  const response = await oAuth2Client.getIapPublicKeys();
  const ticket = await oAuth2Client.verifySignedJwtWithCertsAsync(
    iapJwt,
    response.pubkeys,
    expectedAudience,
    ['https://cloud.google.com/iap']
  );
  // Print out the info contained in the IAP ID token
  console.log(ticket);
}

verify().catch(console.error);

PHP

namespace Google\Cloud\Samples\Iap;

# Imports Google auth libraries for IAP validation
use Google\Auth\AccessToken;

/**
 * Validate a JWT passed to your App Engine app by Identity-Aware Proxy.
 *
 * @param string $iap_jwt The contents of the X-Goog-IAP-JWT-Assertion header.
 * @param string $cloud_project_number The project *number* for your Google
 *     Cloud project. This is returned by 'gcloud projects describe $PROJECT_ID',
 *     or in the Project Info card in Cloud Console.
 * @param string $cloud_project Your Google Cloud Project ID.
 *
 * @return (user_id, user_email).
 */
function validate_jwt_from_app_engine($iap_jwt, $cloud_project_number, $cloud_project_id)
{
    $expected_audience = sprintf(
        '/projects/%s/apps/%s',
        $cloud_project_number,
        $cloud_project_id
    );
    return validate_jwt($iap_jwt, $expected_audience);
}

/**
 * Validate a JWT passed to your Compute / Container Engine app by Identity-Aware Proxy.
 *
 * @param string $iap_jwt The contents of the X-Goog-IAP-JWT-Assertion header.
 * @param string $cloud_project_number The project *number* for your Google
 *     Cloud project. This is returned by 'gcloud projects describe $PROJECT_ID',
 *     or in the Project Info card in Cloud Console.
 * @param string $backend_service_id The ID of the backend service used to access the
 *     application. See https://cloud.google.com/iap/docs/signed-headers-howto
 *     for details on how to get this value.
 *
 * @return (user_id, user_email).
 */
function validate_jwt_from_compute_engine($iap_jwt, $cloud_project_number, $backend_service_id)
{
    $expected_audience = sprintf(
        '/projects/%s/global/backendServices/%s',
        $cloud_project_number,
        $backend_service_id
    );
    return validate_jwt($iap_jwt, $expected_audience);
}

function validate_jwt($iap_jwt, $expected_audience)
{
    // Validate the signature using the IAP cert URL.
    $token = new AccessToken();
    $jwt = $token->verify($iap_jwt, [
        'certsLocation' => AccessToken::IAP_CERT_URL
    ]);

    if (!$jwt) {
        return print('Failed to validate JWT: Invalid JWT');
    }

    // Validate token by checking issuer and audience fields.
    assert($jwt['iss'] == 'https://cloud.google.com/iap');
    assert($jwt['aud'] == $expected_audience);

    // Return the user identity (subject and user email) if JWT verification is successful.
    return array('sub' => $jwt['sub'], 'email' => $jwt['email']);
}

Python

from google.auth.transport import requests
from google.oauth2 import id_token

def validate_iap_jwt(iap_jwt, expected_audience):
    """Validate an IAP JWT.

    Args:
      iap_jwt: The contents of the X-Goog-IAP-JWT-Assertion header.
      expected_audience: The Signed Header JWT audience. See
          https://cloud.google.com/iap/docs/signed-headers-howto
          for details on how to get this value.

    Returns:
      (user_id, user_email, error_str).
    """

    try:
        decoded_jwt = id_token.verify_token(
            iap_jwt, requests.Request(), audience=expected_audience,
            certs_url='https://www.gstatic.com/iap/verify/public_key')
        return (decoded_jwt['sub'], decoded_jwt['email'], '')
    except Exception as e:
        return (None, None, '**ERROR: JWT validation error {}**'.format(e))

Ruby

# iap_jwt = "The contents of the X-Goog-Iap-Jwt-Assertion header"
# project_number = "The project *number* for your Google Cloud project"
# project_id = "Your Google Cloud project ID"
# backend_service_id = "Your Compute Engine backend service ID"
require "googleauth"

audience = nil
if project_number && project_id
  # Expected audience for App Engine
  audience = "/projects/#{project_number}/apps/#{project_id}"
elsif project_number && backend_service_id
  # Expected audience for Compute Engine
  audience = "/projects/#{project_number}/global/backendServices/#{backend_service_id}"
end

# The client ID as the target audience for IAP
payload = Google::Auth::IDTokens.verify_iap iap_jwt, aud: audience

puts payload

if audience.nil?
  puts "Audience not verified! Supply a project_number and project_id to verify"
end

Validierungscode testen

Wenn Sie Ihre Anwendung mit den Abfrageparametern secure_token_test aufrufen, enthält IAP ein ungültiges JWT. Damit können Sie sicherstellen, dass Ihre JWT-Validierungslogik alle denkbaren Fehlerszenarien abdeckt, und prüfen, wie sich Ihre Anwendung bei einem ungültigen JWT verhält.

Ausnahme für Systemdiagnose erstellen

Wie bereits erwähnt, verwenden die Compute Engine- und GKE-Systemdiagnosen keine JWT-Header und IAP verarbeitet keine Systemdiagnosen. Sie müssen also die Systemdiagnose und die Anwendung so konfigurieren, dass der Zugriff auf die Systemdiagnose zulässig ist.

Systemdiagnose konfigurieren

Wenn Sie noch keinen Pfad für die Systemdiagnose festgelegt haben, geben Sie in der Cloud Console einen nicht vertraulichen Pfad dafür an. Achten Sie darauf, dass dieser Pfad von keiner anderen Ressource verwendet wird.

  1. Rufen Sie die Seite Systemdiagnosen in der Cloud Console auf.
    Zur Seite "Systemdiagnosen"
  2. Klicken Sie auf die Systemdiagnose, die Sie für Ihre Anwendung verwenden, und anschließend auf Bearbeiten.
  3. Fügen Sie unter Anfragepfad einen nicht vertraulichen Pfadnamen hinzu. Gibt den URL-Pfad an, den Google Cloud beim Senden von Systemdiagnoseanfragen verwendet. Wenn nichts angegeben ist, werden Systemdiagnoseanfragen an / gesendet.
  4. Klicken Sie auf Speichern.

JWT-Validierung konfigurieren

Fügen Sie dem Code, der die JWT-Validierungsroutine aufruft, eine Bedingung hinzu, die den HTTP-Status 200 für den Systemdiagnoseanfragepfad ausgibt. Beispiel:

if HttpRequest.path_info = '/HEALTH_CHECK_REQUEST_PATH'
  return HttpResponse(status=200)
else
  VALIDATION_FUNCTION

JWTs für externe Identitäten

Wenn Sie IAP mit externen Identitäten verwenden, gibt IAP wie bei Google-Identitäten weiterhin ein signiertes JWT bei jeder authentifizierten Anfrage aus. Es gibt jedoch einige Unterschiede.

Anbieterinformationen

Bei Verwendung externer Identitäten enthält die JWT-Nutzlast eine Anforderung namens gcip. Diese Anforderung beinhaltet Informationen über den Nutzer, z. B. seine E-Mail-Adresse und seine Foto-URL, sowie zusätzliche anbieterspezifische Attribute.

Im Folgenden finden Sie ein Beispiel für das JWT eines Nutzers, der sich mit Facebook angemeldet hat:

"gcip": '{
  "auth_time": 1553219869,
  "email": "facebook_user@gmail.com",
  "email_verified": false,
  "firebase": {
    "identities": {
      "email": [
        "facebook_user@gmail.com"
      ],
      "facebook.com": [
        "1234567890"
      ]
    },
    "sign_in_provider": "facebook.com",
  },
  "name": "Facebook User",
  "picture: "https://graph.facebook.com/1234567890/picture",
  "sub": "gZG0yELPypZElTmAT9I55prjHg63"
}',

Die Felder email und sub

Wenn ein Nutzer von Identity Platform authentifiziert wurde, werden den Feldern email und sub des JWT der Tokenaussteller von Identity Platform und die verwendete Mandanten-ID (wenn vorhanden) vorangestellt. Beispiel:

"email": "securetoken.google.com/PROJECT-ID/TENANT-ID:demo_user@gmail.com",
"sub": "securetoken.google.com/PROJECT-ID/TENANT-ID:gZG0yELPypZElTmAT9I55prjHg63"

Zugriff mit sign_in_attributes steuern

IAM wird nicht für die Verwendung externer Identitäten unterstützt. Sie können stattdessen aber den Zugriff mit Anforderungen steuern, die im Feld sign_in_attributes eingebettet sind. Angenommen, ein Nutzer meldet sich mit einem SAML-Anbieter an:

{
  "aud": "/projects/project_number/apps/my_project_id",
  "gcip": '{
    "auth_time": 1553219869,
    "email": "demo_user@gmail.com",
    "email_verified": true,
    "firebase": {
      "identities": {
        "email": [
          "demo_user@gmail.com"
        ],
        "saml.myProvider": [
          "demo_user@gmail.com"
        ]
      },
      "sign_in_attributes": {
        "firstname": "John",
        "group": "test group",
        "role": "admin",
        "lastname": "Doe"
      },
      "sign_in_provider": "saml.myProvider",
      "tenant": "my_tenant_id"
    },
    "sub": "gZG0yELPypZElTmAT9I55prjHg63"
  }',
  "email": "securetoken.google.com/my_project_id/my_tenant_id:demo_user@gmail.com",
  "exp": 1553220470,
  "iat": 1553219870,
  "iss": "https://cloud.google.com/iap",
  "sub": "securetoken.google.com/my_project_id/my_tenant_id:gZG0yELPypZElTmAT9I55prjHg63"
}

Sie können der Anwendung dann eine Logik wie mit dem folgenden Code hinzufügen und so den Zugriff auf Nutzer mit einer gültigen Rolle einschränken:

const gcipClaims = JSON.parse(decodedIapJwtClaims.gcip);
if (gcipClaims &&
    gcipClaims.firebase &&
    gcipClaims.firebase.sign_in_attributes &&
    gcipClaims.firebase.sign_in_attribute.role === 'admin') {
  // Allow access to admin restricted resource.
} else {
  // Block access.
}

Zusätzliche Nutzerattribute von Identity Platform-SAML- und -OIDC-Anbietern können über die verschachtelte Anforderung gcipClaims.gcip.firebase.sign_in_attributes aufgerufen werden.