Questa pagina descrive come eseguire l'autenticazione a una risorsa protetta da Identity-Aware Proxy (IAP) da un account utente o da un account di servizio.
Un account utente appartiene a un singolo utente. Autentichi un account utente quando la tua applicazione richiede l'accesso a risorse protette da IAP per conto di un utente. Per maggiori informazioni, vedi Account utente.
Un account di servizio appartiene a un'applicazione anziché a un singolo utente. Autentichi un account di servizio quando vuoi consentire a un'applicazione di accedere alle tue risorse protette con IAP. Per maggiori informazioni, consulta la pagina Account di servizio.
Prima di iniziare
Prima di iniziare, ti serviranno:
- Un'applicazione protetta da IAP a cui vuoi connetterti in modo programmatico utilizzando un account sviluppatore, un account di servizio o le credenziali di app mobile.
Autenticazione di un account utente
Puoi abilitare l'accesso degli utenti alla tua app da un'app desktop o mobile per consentire a un programma di interagire con una risorsa protetta da IAP.
Autenticazione da un'app mobile
- Crea o utilizza un ID client OAuth 2.0 esistente per la tua app mobile. Per utilizzare un ID client OAuth 2.0 esistente, segui i passaggi descritti in Come condividere client OAuth.
- Autorizza l'ID client OAuth per l'accesso programmatico all'applicazione.
- Ottieni un token ID per l'ID client protetto con IAP.
- Android: utilizza
l'API Accedi con Google per richiedere
un token
OpenID Connect
(OIDC). Imposta l'ID client
requestIdToken
sull'ID client della risorsa alla quale ti stai connettendo. - iOS: utilizza Accedi con Google per ricevere un token ID.
- Android: utilizza
l'API Accedi con Google per richiedere
un token
OpenID Connect
(OIDC). Imposta l'ID client
- Includi il token ID in un'intestazione
Authorization: Bearer
per effettuare la richiesta autenticata alla risorsa protetta da IAP.
Autenticazione da un'app desktop
Questa sezione descrive come autenticare un account utente da una riga di comando desktop.
- Per consentire agli sviluppatori di accedere all'applicazione dalla riga di comando, crea un ID client OAuth 2.0 desktop o condividi un ID client OAuth desktop esistente.
- Autorizza l'ID client OAuth per l'accesso programmatico all'applicazione.
Accesso all'applicazione
Ogni sviluppatore che vuole accedere a un'app protetta da IAP dovrà prima effettuare l'accesso. Puoi pacchettizzare il processo in uno script, ad esempio utilizzando gcloud CLI. Di seguito è riportato un esempio in cui viene utilizzato curl per accedere e generare un token che possa essere utilizzato per accedere all'applicazione:
- Accedi al tuo account che ha accesso alla risorsa Google Cloud.
-
Avvia un server locale che possa eseguire l'eco delle richieste in entrata.
$ nc -k -l 4444
NOTA: il comando utilizza l'utilità NetCat. Puoi utilizzare l'utilità che preferisci. -
Vai al seguente URI, dove
DESKTOP_CLIENT_ID
è l'ID client app desktop: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
-
Nell'output del server locale, cerca i parametri della richiesta. Dovresti vedere
qualcosa di simile al seguente:
GET /?code=$CODE&scope=email%20openid%20https://www.googleapis.com/auth/userinfo.email&hd=google.com&prompt=consent HTTP/1.1
copia il CODICE per sostituireAUTH_CODE
sotto insieme all'ID client e al secret di App desktop: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
Questo codice restituisce un oggetto JSON con un campo
id_token
che puoi utilizzare per accedere all'applicazione.
Accesso all'applicazione
Per accedere all'app, usa id_token
come segue:
curl --verbose --header 'Authorization: Bearer ID_TOKEN' URL
Aggiorna token
Puoi utilizzare il token di aggiornamento generato durante il flusso di accesso per ottenere nuovi token ID. Questo è utile quando il token ID originale scade. Ogni token ID è valido per circa un'ora, durante il quale puoi effettuare più richieste a un'app specifica.
Di seguito è riportato un esempio in cui viene utilizzato curl per ottenere un nuovo token ID. Nell'esempio seguente, REFRESH_TOKEN
è il token del flusso di accesso.
DESKTOP_CLIENT_ID
e
DESKTOP_CLIENT_SECRET
sono
gli stessi utilizzati nel flusso di accesso:
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
Questo codice restituisce un oggetto JSON con un nuovo campo id_token
che puoi utilizzare per accedere all'app.
Autenticazione di un account di servizio
Puoi utilizzare un account di servizio JWT o un token OpenID Connect (OIDC) per autenticare un account di servizio con una risorsa protetta da IAP. La seguente tabella illustra alcune delle differenze tra i diversi token di autenticazione e le relative funzionalità.
Funzionalità di autenticazione | JWT dell'account di servizio | Token OpenID Connect |
---|---|---|
Supporto dell'accesso sensibile al contesto | ||
Requisito per l'ID client OAuth 2.0 | ||
Ambito token | URL della risorsa protetta da IAP | ID client OAuth 2.0 |
Autenticazione con un account di servizio JWT
L'autenticazione di un account di servizio tramite JWT prevede i seguenti passaggi principali:
Concedi all'account di servizio che chiama il ruolo Creatore token account di servizio (
roles/iam.serviceAccountTokenCreator
).Il ruolo concede alle entità l'autorizzazione per creare credenziali di breve durata, come JWT.
Crea un JWT per la risorsa protetta da IAP.
Firma il JWT utilizzando la chiave privata dell'account di servizio.
Creazione del JWT
Il JWT creato dovrebbe avere un payload simile all'esempio seguente:
{ "iss": SERVICE_ACCOUNT_EMAIL_ADDRESS, "sub": SERVICE_ACCOUNT_EMAIL_ADDRESS, "aud": TARGET_URL, "iat": IAT, "exp": EXP, }
Per i campi
iss
esub
, specifica l'indirizzo email dell'account di servizio. Si trova nel campoclient_email
del file JSON dell'account di servizio o viene passato. Formato tipico:service-account@PROJECT_ID.iam.gserviceaccount.com
Per il campo
aud
, specifica l'URL della risorsa protetta da IAP.Per il campo
iat
, specifica l'ora dell'epoca Unix attuale, mentre per il campoexp
specifica un'ora entro 3600 secondi. Definisce quando scade il JWT.
Firmare il JWT
Per firmare il JWT, puoi utilizzare uno dei seguenti metodi:
- Utilizza l'API delle credenziali IAM per firmare un JWT senza richiedere l'accesso diretto a una chiave privata.
- Usa un file di chiave delle credenziali locali per firmare il JWT localmente.
Firma del JWT utilizzando l'API IAM Service Account Credentials
Utilizza l'API IAM Service Account Credentials per firmare un JWT di un account di servizio. Il metodo recupera la chiave privata associata al tuo account di servizio e la utilizza per firmare il payload JWT. Ciò consente la firma di un JWT senza accesso diretto a una chiave privata.
Per eseguire l'autenticazione su IAP, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configurare l'autenticazione per un ambiente di sviluppo locale.
gcloud
Esegui questo comando per preparare una richiesta con il payload JWT:
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
Utilizza il seguente comando Google Cloud CLI per firmare il payload in
request.json
:gcloud iam service-accounts sign-jwt --iam-account=SERVICE_ACCOUNT_EMAIL_ADDRESS claim.json output.jwt
Se la richiesta viene approvata,
output.jwt
contiene un JWT firmato.Utilizza il JWT per accedere alla risorsa protetta da IAP.
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
Se la richiesta viene approvata, lo script restituisce un JWT firmato. Utilizza il JWT per accedere alla risorsa protetta da IAP.
curl
Esegui questo comando per preparare una richiesta con il payload JWT:
cat << EOF > request.json { "payload": JWT_PAYLOAD } EOF
Firma il JWT utilizzando l'API IAM Service Account Credentials:
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"
Se la richiesta viene approvata, nella risposta è presente un JWT firmato.
Utilizza il JWT per accedere alla risorsa protetta da IAP.
Firma del JWT da un file di chiave delle credenziali locali
I JWT vengono firmati utilizzando la chiave privata dell'account di servizio.
Se hai un file della chiave dell'account di servizio, il JWT può essere firmato localmente.
Lo script invia un'intestazione JWT insieme al payload. Per il campo kid
nell'intestazione, utilizza l'ID della chiave privata dell'account di servizio, che si trova nel campo private_key_id
del file JSON delle credenziali dell'account di servizio.
La chiave viene utilizzata anche per firmare il JWT.
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
Il risultato è un JWT firmato.
Accesso all'applicazione
In ogni caso, per accedere all'app, utilizza
signed-jwt
come segue:
curl --verbose --header 'Authorization: Bearer SIGNED_JWT' URL
Autenticazione con un token OIDC
- Crea o utilizza un ID client OAuth 2.0 esistente. Per utilizzare un ID client OAuth 2.0 esistente, segui i passaggi descritti in Come condividere client OAuth.
- Autorizza l'ID client OAuth per l'accesso programmatico all'applicazione.
Devi inoltre aggiungere l'account di servizio all'elenco per gli accessi per il progetto protetto da IAP. I seguenti esempi di codice mostrano come ottenere un token OIDC. Devi includere il token in un'intestazione Authorization: Bearer
per effettuare la richiesta di autenticazione alla risorsa protetta da IAP.
Ottenere un token OIDC per l'account di servizio predefinito
Se vuoi ottenere un token OIDC per l'account di servizio predefinito per Compute Engine, App Engine o Cloud Run, puoi utilizzare il seguente esempio di codice per generare il token e accedere a una risorsa protetta da IAP:
C#
Go
Per eseguire l'autenticazione su IAP, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Java
Node.js
PHP
Per eseguire l'autenticazione su IAP, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione su IAP, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Ruby
Per eseguire l'autenticazione su IAP, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Recupero di un token OIDC da un file della chiave dell'account di servizio locale
Se hai un file delle chiavi dell'account di servizio, puoi adattare gli esempi di codice precedenti per fornire il file delle chiavi dell'account di servizio.
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 "$@"
Ottenere un token OIDC in tutti gli altri casi
In tutti gli altri casi, utilizza l'API delle credenziali IAM per generare un token OIDC impersonando un account di servizio di destinazione proprio prima di accedere a una risorsa protetta da IAP. Questa procedura prevede i seguenti passaggi:
Fornisci all'account di servizio chiamante (l'account di servizio associato al codice che sta ricevendo il token ID) con il ruolo Creatore token di identità OpenID Connect dell'account di servizio (
roles/iam.serviceAccountOpenIdTokenCreator
).In questo modo l'account di servizio chiamante può impersonare l'account di servizio di destinazione.
Utilizza le credenziali fornite dall'account di servizio chiamante per chiamare il metodo generateIdToken sull'account di servizio di destinazione.
Imposta il campo
audience
sul tuo ID client.
Per istruzioni dettagliate, consulta Creare un token ID.
Autenticazione dall'intestazione Proxy-Authorization
Se la tua applicazione utilizza l'intestazione della richiesta Authorization
, puoi
includere il token ID in un'intestazione Proxy-Authorization: Bearer
. Se in un'intestazione Proxy-Authorization
viene trovato un token ID valido, IAP autorizza la richiesta con questo token. Dopo aver autorizzato la richiesta, IAP passa l'intestazione Authorization
alla tua applicazione senza elaborare i contenuti.
Se non viene trovato alcun token ID valido nell'intestazione Proxy-Authorization
, IAP continua a elaborare l'intestazione Authorization
e rimuove l'intestazione Proxy-Authorization
prima di passare la richiesta all'applicazione.
Passaggi successivi
- Scopri di più sull'autorizzazione: token di connessione.
- Prova la funzionalità Accedi per Android o Accedi per iOS.