Auf dieser Seite wird beschrieben, wie Sie sich über ein Nutzerkonto oder ein Dienstkonto bei einer Ressource authentifizieren, die mit Identity-Aware Proxy (IAP) gesichert ist.
Ein Nutzerkonto gehört zu einem einzelnen Nutzer. Ein Nutzerkonto muss authentifiziert werden, wenn Ihre Anwendung im Namen eines Nutzers auf Ressourcen zugreifen soll, die mit IAP gesichert sind. Weitere Informationen finden Sie unter Nutzerkonten.
Ein Dienstkonto ist keinem einzelnen Nutzer, sondern einer Anwendung zugeordnet. Ein Dienstkonto muss authentifiziert werden, wenn Sie einer Anwendung Zugriff auf Ihre mit IAP gesicherten Ressourcen gewähren möchten. Weitere Informationen finden Sie unter Dienstkonten.
Hinweise
Für den Start ist Folgendes erforderlich:
- Eine mit IAP gesicherte Anwendung, zu der Sie programmatisch eine Verbindung über ein Entwicklerkonto, ein Dienstkonto oder die Anmeldedaten einer mobilen App herstellen möchten.
Nutzerkonto authentifizieren
Sie können Nutzern den Zugriff auf Ihre Anwendung von einer Desktop- oder mobilen App aus ermöglichen, damit ein Programm mit einer mit IAP gesicherten Ressource interagieren kann.
Von einer mobilen App aus authentifizieren
- Erstellen Sie eine OAuth 2.0-Client-ID oder verwenden Sie eine vorhandene OAuth 2.0-Client-ID für Ihre mobile App. Wenn Sie eine vorhandene OAuth 2.0-Client-ID verwenden möchten, folgen Sie der Anleitung unter OAuth-Clients freigeben.
- Setzen Sie die OAuth-Client-ID für den programmatischen Zugriff auf die Anwendung auf die Zulassungsliste.
- Rufen Sie ein ID-Token für die mit IAP gesicherte Client-ID ab.
- Android: Fordern Sie mit der Google Sign-In API ein OpenID Connect-Token (OIDC) an. Geben Sie für die Client-ID von
requestIdToken
die Client-ID für die Ressource an, zu der Sie eine Verbindung herstellen möchten. - iOS: Fordern Sie mit Google Log-in ein ID-Token an.
- Android: Fordern Sie mit der Google Sign-In API ein OpenID Connect-Token (OIDC) an. Geben Sie für die Client-ID von
- Fügen Sie das ID-Token in einen
Authorization: Bearer
-Header ein, um die authentifizierte Anfrage an die mit IAP gesicherte Ressource zu senden.
Von einer Desktopanwendung aus authentifizieren
In diesem Abschnitt wird beschrieben, wie Sie ein Nutzerkonto von einer Desktop-Befehlszeile aus authentifizieren können.
- Damit Entwickler über die Befehlszeile auf Ihre Anwendung zugreifen können, erstellen Sie eine OAuth 2.0-Desktop-Client-ID oder geben Sie eine vorhandene OAuth-Client-ID für Computer frei.
- Setzen Sie die OAuth-Client-ID für den programmatischen Zugriff auf die Anwendung auf die Zulassungsliste.
Bei der Anwendung anmelden
Jeder Entwickler, der auf eine mit IAP gesicherte Anwendung zugreifen möchte, muss sich zuerst anmelden. Sie können den Prozess in einem Skript bündeln, z. B. mithilfe der gcloud CLI. Im Folgenden finden Sie ein Beispiel mit curl, mit dem Sie sich anmelden und ein Token generieren können, um damit auf die Anwendung zuzugreifen:
- Melden Sie sich in Ihrem Konto an, das Zugriff auf die Google Cloud-Ressource hat.
-
Starten Sie einen lokalen Server, der die eingehenden Anfragen wiederholen kann.
$ nc -k -l 4444
HINWEIS: Für den Befehl wird das Dienstprogramm NetCat verwendet. Sie können ein Dienstprogramm Ihrer Wahl verwenden. -
Öffnen Sie den folgenden URI, wobei
DESKTOP_CLIENT_ID
die Client-ID für die Desktop-App ist:https://accounts.google.com/o/oauth2/v2/auth?client_id=DESKTOP_CLIENT_ID&response_type=code&scope=openid%20email&access_type=offline&redirect_uri=http://localhost:4444&cred_ref=true
-
Suchen Sie in der Ausgabe des lokalen Servers nach den Anfrageparametern. Sie sollten in etwa Folgendes sehen:
GET /?code=$CODE&scope=email%20openid%20https://www.googleapis.com/auth/userinfo.email&hd=google.com&prompt=consent HTTP/1.1
Kopieren Sie den CODE und ersetzen SieAUTH_CODE
unten zusammen mit der Client-ID und dem Secret für die Desktop-App:curl --verbose \ --data client_id=DESKTOP_CLIENT_ID \ --data client_secret=DESKTOP_CLIENT_SECRET \ --data code=AUTH_CODE \ --data redirect_uri=http://localhost:4444 \ --data grant_type=authorization_code \ https://oauth2.googleapis.com/token
Dieser Code gibt ein JSON-Objekt mit dem Feld
id_token
zurück, mit dem Sie auf die Anwendung zugreifen können.
Auf die Anwendung zugreifen
Verwenden Sie id_token
so, um auf die Anwendung zuzugreifen:
curl --verbose --header 'Authorization: Bearer ID_TOKEN' URL
Aktualisierungstoken
Sie können das während des Anmeldevorgangs generierte Aktualisierungstoken verwenden, um neue ID-Tokens abzurufen. Das ist nützlich, wenn das ursprüngliche ID-Token abläuft. Jedes ID-Token ist etwa eine Stunde lang gültig. In dieser Zeit können Sie mehrere Anfragen an eine bestimmte App senden.
Im folgenden Beispiel wird mit curl ein Aktualisierungstoken verwendet, um ein neues ID-Token abzurufen. Im folgenden Beispiel ist REFRESH_TOKEN
das Token für den Anmeldevorgang.
DESKTOP_CLIENT_ID
und DESKTOP_CLIENT_SECRET
sind identisch mit denjenigen, die im Anmeldevorgang verwendet werden:
curl --verbose \ --data client_id=DESKTOP_CLIENT_ID \ --data client_secret=DESKTOP_CLIENT_SECRET \ --data refresh_token=REFRESH_TOKEN \ --data grant_type=refresh_token \ https://oauth2.googleapis.com/token
Dieser Code gibt ein JSON-Objekt mit einem neuen id_token
-Feld zurück, mit dem Sie auf die Anwendung zugreifen können.
Dienstkonto authentifizieren
Sie können ein Dienstkonto-JWT oder ein OpenID Connect-Token (OIDC) verwenden, um ein Dienstkonto mit einer mit IAP gesicherten Ressource zu authentifizieren. In der folgenden Tabelle sind einige der Unterschiede zwischen den verschiedenen Authentifizierungstokens und ihren Funktionen aufgeführt.
Authentifizierungsfunktionen | Dienstkonto-JWT | OpenID Connect-Token |
---|---|---|
Unterstützung für kontextsensitiven Zugriff | ||
Anforderung der OAuth 2.0-Client-ID | ||
Tokenbereich | URL der mit IAP gesicherten Ressource | OAuth 2.0-Client-ID |
Mit einem Dienstkonto-JWT authentifizieren
Die Authentifizierung eines Dienstkontos mithilfe eines JWT umfasst die folgenden Hauptschritte:
Gewähren Sie dem aufrufenden Dienstkonto die Rolle Ersteller von Dienstkonto-Tokens (
roles/iam.serviceAccountTokenCreator
).Die Rolle gewährt Hauptkonten die Berechtigung, kurzlebige Anmeldedaten wie JWTs zu erstellen.
Erstellen Sie ein JWT für die mit IAP gesicherte Ressource.
Signieren Sie das JWT mit dem privaten Schlüssel des Dienstkontos.
JWT erstellen
Das erstellte JWT sollte eine Nutzlast ähnlich dem folgenden Beispiel haben:
{ "iss": SERVICE_ACCOUNT_EMAIL_ADDRESS, "sub": SERVICE_ACCOUNT_EMAIL_ADDRESS, "aud": TARGET_URL, "iat": IAT, "exp": EXP, }
Geben Sie in den Feldern
iss
undsub
die E-Mail-Adresse des Dienstkontos an. Sie befindet sich in der JSON-Datei des Dienstkontos im Feldclient_email
oder wird übergeben. Typisches Format:service-account@PROJECT_ID.iam.gserviceaccount.com
Geben Sie im Feld
aud
die URL der mit IAP gesicherten Ressource an.Geben Sie im Feld
iat
die aktuelle Unix-Epochenzeit und im Feldexp
einen Zeitpunkt innerhalb von 3.600 Sekunden an. Gibt an, wann das JWT abläuft.
JWT signieren
Du kannst das JWT mit einer der folgenden Methoden signieren:
- Mit der IAM Credentials API können Sie ein JWT ohne direkten Zugriff auf einen privaten Schlüssel signieren.
- Verwende eine lokale Schlüsseldatei für Anmeldedaten, um das JWT lokal zu signieren.
JWT mit der IAM Service Account Credentials API signieren
Verwenden Sie die IAM Service Account Credentials API, um ein Dienstkonto-JWT zu signieren. Die Methode ruft den privaten Schlüssel ab, der mit deinem Dienstkonto verknüpft ist, und signiert damit die JWT-Nutzlast. Dadurch kann ein JWT ohne direkten Zugriff auf einen privaten Schlüssel signiert werden.
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei IAP zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
gcloud
Führen Sie den folgenden Befehl aus, um eine Anfrage mit der JWT-Nutzlast vorzubereiten:
cat > claim.json << EOM { "iss": "SERVICE_ACCOUNT_EMAIL_ADDRESS", "sub": "SERVICE_ACCOUNT_EMAIL_ADDRESS", "aud": "TARGET_URL", "iat": $(date +%s), "exp": $((`date +%s` + 3600)) } EOM
Verwenden Sie den folgenden Google Cloud CLI-Befehl, um die Nutzlast in
request.json
zu signieren:gcloud iam service-accounts sign-jwt --iam-account=SERVICE_ACCOUNT_EMAIL_ADDRESS claim.json output.jwt
Bei einer erfolgreichen Anfrage enthält
output.jwt
ein signiertes JWT.Verwenden Sie das JWT, um auf Ihre mit IAP gesicherte Ressource zuzugreifen.
Python
import datetime
import json
import google.auth
from google.cloud import iam_credentials_v1
import jwt
def generate_jwt_payload(service_account_email: str, resource_url: str) -> str:
"""Generates JWT payload for service account.
The resource url provided must be the same as the url of the IAP secured resource.
Args:
service_account_email (str): Specifies service account JWT is created for.
resource_url (str): Specifies scope of the JWT, the URL that the JWT will be allowed to access.
Returns:
A signed-jwt that can be used to access IAP protected applications.
Access the application with the JWT in the Authorization Header.
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
"""
iat = datetime.datetime.now(tz=datetime.timezone.utc)
exp = iat + 3600
return json.dumps({
'iss': service_account_email,
'sub': service_account_email,
'aud': resource_url,
'iat': iat,
'exp': exp,
})
def sign_jwt(target_sa: str, resource_url: str) -> str:
"""Signs JWT payload using ADC and IAM credentials API.
Args:
target_sa (str): Service Account JWT is being created for.
iap.webServiceVersions.accessViaIap permission is required.
resource_url (str): Audience of the JWT, and scope of the JWT token.
This is the url of the IAP protected application.
Returns:
A signed-jwt that can be used to access IAP protected apps.
"""
source_credentials, _ = google.auth.default()
iam_client = iam_credentials_v1.IAMCredentialsClient(credentials=source_credentials)
return iam_client.sign_jwt(
name=iam_client.service_account_path('-', target_sa),
payload=generate_jwt_payload(target_sa, resource_url),
).signed_jwt
Bei einer erfolgreichen Anfrage gibt das Skript ein signiertes JWT zurück. Verwenden Sie das JWT, um auf Ihre mit IAP gesicherte Ressource zuzugreifen.
curl
Führen Sie den folgenden Befehl aus, um eine Anfrage mit der JWT-Nutzlast vorzubereiten:
cat << EOF > request.json { "payload": JWT_PAYLOAD } EOF
Signieren Sie das JWT mithilfe der IAM Service Account Credentials API:
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ -d @request.json \ "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL_ADDRESS:signJwt"
Bei einer erfolgreichen Anfrage enthält die Antwort ein signiertes JWT.
Verwenden Sie das JWT, um auf Ihre mit IAP gesicherte Ressource zuzugreifen.
JWT aus einer lokalen Schlüsseldatei für Anmeldedaten signieren
JWTs werden mit dem privaten Schlüssel des Dienstkontos signiert.
Wenn Sie eine Dienstkonto-Schlüsseldatei haben, kann das JWT lokal signiert werden.
Das Skript sendet zusammen mit der Nutzlast einen JWT-Header. Verwenden Sie für das Feld kid
im Header die ID des privaten Schlüssels des Dienstkontos. Diese befindet sich im Feld private_key_id
der JSON-Datei mit den Anmeldedaten des Dienstkontos.
Der Schlüssel wird auch zum Signieren des JWT verwendet.
Python
import time
import jwt
import json
def generate_jwt_payload(service_account_email, resource_url):
"""Generates JWT payload for service account.
The resource url provided must be the same as the url of the IAP secured resource.
Args:
service_account_email (str): Specifies service account JWT is created for.
resource_url (str): Specifies scope of the JWT, the URL that the JWT will be allowed to access.
Returns:
A signed-jwt that can be used to access IAP protected applications.
Access the application with the JWT in the Authorization Header.
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
"""
iat = datetime.datetime.now(tz=datetime.timezone.utc)
exp = iat + 3600
return json.dumps({
'iss': service_account_email,
'sub': service_account_email,
'aud': resource_url,
'iat': iat,
'exp': exp,
})
def sign_jwt_with_key_file(credential_key_file_path, resource_url):
"""Signs JWT payload using local service account credential key file.
Args:
credential_key_file_path (str): Path to the downloaded JSON credentials of the service
account the JWT is being created for.
resource_url (str): Scope of JWT token, This is the url of the IAP protected application.
Returns:
A service account JWT created with a downloaded private key.
"""
with open(credential_key_file_path, 'r') as credential_key_file:
key_data = json.load(credential_key_file)
PRIVATE_KEY_ID_FROM_JSON = key_data["private_key_id"]
PRIVATE_KEY_FROM_JSON = key_data["private_key"]
SERVICE_ACCOUNT_EMAIL = key_data["client_email"]
# Sign JWT with private key and store key id in the header
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
payload = generate_jwt_payload(service_account_email=SERVICE_ACCOUNT_EMAIL, resource_url=resource_url)
signed_jwt = jwt.encode(
payload,
PRIVATE_KEY_FROM_JSON,
headers=additional_headers,
algorithm='RS256',
)
return signed_jwt
Das Ergebnis ist ein signiertes JWT.
Auf die Anwendung zugreifen
Für den Zugriff auf die Anwendung müssen Sie in allen Fällen signed-jwt
so verwenden:
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
Mit einem OIDC-Token authentifizieren
- Erstellen Sie eine OAuth 2.0-Client-ID oder verwenden Sie eine vorhandene. Wenn Sie eine vorhandene OAuth 2.0-Client-ID verwenden möchten, folgen Sie der Anleitung unter OAuth-Clients freigeben.
- Setzen Sie die OAuth-Client-ID für den programmatischen Zugriff auf die Anwendung auf die Zulassungsliste.
Außerdem müssen Sie das Dienstkonto der Zugriffsliste für das mit IAP gesicherte Projekt hinzufügen. Die folgenden Codebeispiele zeigen, wie Sie ein OIDC-Token erhalten. Sie müssen das Token in einen Authorization: Bearer
-Header aufnehmen, um die Authentifizierungsanfrage an die mit IAP gesicherte Ressource zu senden.
OIDC-Token für das Standarddienstkonto abrufen
Wenn Sie ein OIDC-Token für das Standarddienstkonto für Compute Engine, App Engine oder Cloud Run abrufen möchten, können Sie das folgende Codebeispiel verwenden, um das Token für den Zugriff auf eine mit IAP gesicherte Ressource zu generieren:
C#
Go
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei IAP zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Java
Node.js
PHP
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei IAP zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Python
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei IAP zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
Ruby
Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei IAP zu authentifizieren. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten.
OIDC-Token aus einer lokalen Dienstkonto-Schlüsseldatei abrufen
Wenn Sie eine Dienstkonto-Schlüsseldatei haben, können Sie die vorherigen Codebeispiele anpassen, um die Dienstkonto-Schlüsseldatei bereitzustellen.
Bash
#!/usr/bin/env bash
set -euo pipefail
get_token() {
# Get the bearer token in exchange for the service account credentials.
local service_account_key_file_path="${1}"
local iap_client_id="${2}"
local iam_scope="https://www.googleapis.com/auth/iam"
local oauth_token_uri="https://www.googleapis.com/oauth2/v4/token"
local private_key_id="$(cat "${service_account_key_file_path}" | jq -r '.private_key_id')"
local client_email="$(cat "${service_account_key_file_path}" | jq -r '.client_email')"
local private_key="$(cat "${service_account_key_file_path}" | jq -r '.private_key')"
local issued_at="$(date +%s)"
local expires_at="$((issued_at + 600))"
local header="{'alg':'RS256','typ':'JWT','kid':'${private_key_id}'}"
local header_base64="$(echo "${header}" | base64)"
local payload="{'iss':'${client_email}','aud':'${oauth_token_uri}','exp':${expires_at},'iat':${issued_at},'sub':'${client_email}','target_audience':'${iap_client_id}'}"
local payload_base64="$(echo "${payload}" | base64)"
local signature_base64="$(printf %s "${header_base64}.${payload_base64}" | openssl dgst -binary -sha256 -sign <(printf '%s\n' "${private_key}") | base64)"
local assertion="${header_base64}.${payload_base64}.${signature_base64}"
local token_payload="$(curl -s \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
--data-urlencode "assertion=${assertion}" \
https://www.googleapis.com/oauth2/v4/token)"
local bearer_id_token="$(echo "${token_payload}" | jq -r '.id_token')"
echo "${bearer_id_token}"
}
main(){
# TODO: Replace the following variables:
SERVICE_ACCOUNT_KEY="service_account_key_file_path"
IAP_CLIENT_ID="iap_client_id"
URL="application_url"
# Obtain the ID token.
ID_TOKEN=$(get_token "${SERVICE_ACCOUNT_KEY}" "${IAP_CLIENT_ID}")
# Access the application with the ID token.
curl --header "Authorization: Bearer ${ID_TOKEN}" "${URL}"
}
main "$@"
In allen anderen Fällen ein OIDC-Token abrufen
In allen anderen Fällen verwenden Sie die IAM Credentials API, um ein OIDC-Token zu generieren. Geben Sie dazu die Identität eines Zieldienstkontos an, bevor Sie auf eine mit IAP gesicherte Ressource zugreifen. Dieser Vorgang umfasst die folgenden Schritte:
Geben Sie das aufrufende Dienstkonto (das Dienstkonto, das mit dem Code verknüpft ist, der das ID-Token abruft) mit der Rolle „OpenID Connect Identity Token Creator“ (
roles/iam.serviceAccountOpenIdTokenCreator
) des Dienstkontos an.Dadurch kann das aufrufende Dienstkonto die Identität des Zieldienstkontos übernehmen.
Verwenden Sie die vom aufrufenden Dienstkonto bereitgestellten Anmeldedaten, um die Methode generateIdToken für das Zieldienstkonto aufzurufen.
Geben Sie im Feld
audience
Ihre Client-ID an.
Eine detaillierte Anleitung finden Sie unter ID-Token erstellen.
Authentifizierung über Proxy-Autorisierungs-Header
Wenn Ihre Anwendung den Anfrageheader Authorization
verwendet, können Sie das ID-Token stattdessen in einen Proxy-Authorization: Bearer
-Header einfügen. Wenn in einem Proxy-Authorization
-Header ein gültiges ID-Token gefunden wird, autorisiert IAP die Anfrage damit. Nach der Autorisierung der Anfrage übergibt IAP den Authorization
-Header an Ihre Anwendung, ohne den Inhalt zu verarbeiten.
Wenn im Proxy-Authorization
-Header kein gültiges ID-Token gefunden wird, verarbeitet IAP den Authorization
-Header weiter und entfernt den Proxy-Authorization
-Header, bevor die Anfrage an die Anwendung übergeben wird.