Authentification côté code
Le choix de la méthode (ADC, compte de service attaché, emprunt d'identité, fédération) est traité dans Authentifier un appel à une API. Cette section en donne la traduction en Python, avec la bibliothèque google-auth (pip install google-auth requests), sur laquelle reposent toutes les bibliothèques clientes : ce que renvoie google.auth.default() selon l'environnement, les deux sortes de jetons (jeton d'accès pour appeler une API Google, jeton d'identité pour appeler son propre service), et la vérification d'un jeton reçu. Les exemples suivent google-auth 2.58.
Ce que renvoie ADC
credentials, project_id = google.auth.default() applique l'ordre de recherche d'ADC et renvoie un objet dont la classe dépend de l'environnement. Le code applicatif n'a pas à la tester : un client construit sans credentials= fait le même appel.
| Environnement | Source trouvée | Classe renvoyée |
|---|---|---|
Poste, gcloud auth application-default login |
Fichier ADC de type authorized_user |
google.oauth2.credentials.Credentials |
Poste, même commande avec --impersonate-service-account |
Fichier ADC de type impersonated_service_account |
google.auth.impersonated_credentials.Credentials |
| Cloud Run, Cloud Run functions, VM, GKE avec Workload Identity Federation for GKE | Serveur de métadonnées | google.auth.compute_engine.Credentials |
| Hors de Google Cloud, Workload Identity Federation | Fichier external_account désigné par GOOGLE_APPLICATION_CREDENTIALS |
google.auth.identity_pool.Credentials (jeton OIDC ou SAML lu dans un fichier ou à une URL, certificat X.509), aws.Credentials, pluggable.Credentials (exécutable) |
| Clé de compte de service, en dernier recours | Fichier service_account |
google.oauth2.service_account.Credentials |
project_id vient de la variable GOOGLE_CLOUD_PROJECT, du projet actif de gcloud ou du serveur de métadonnées ; il peut valoir None avec un fichier de fédération. Le passer explicitement aux clients évite de dépendre de cette déduction.
import google.auth
from google.auth.transport.requests import AuthorizedSession
credentials, project_id = google.auth.default(
scopes=["https://www.googleapis.com/auth/cloud-platform"],
quota_project_id="PROJECT_ID",
)
session = AuthorizedSession(credentials) # requests.Session qui pose et renouvelle le jeton
r = session.get(f"https://cloudresourcemanager.googleapis.com/v3/projects/{project_id}")
- Scopes. Les bibliothèques clientes posent elles-mêmes leurs scopes par défaut ;
scopes=ne sert que pour un appel REST direct. Le scopecloud-platformcouvre toutes les API Google Cloud : l'autorisation réelle se règle par IAM, pas par le scope. - Projet de quota. Avec des identifiants d'utilisateur, l'appel est imputé au projet de quota. Il se fixe, du plus local au plus global :
client_options={"quota_project_id": "PROJECT_ID"}sur un client,quota_project_id=degoogle.auth.default(),credentials.with_quota_project("PROJECT_ID"), la variableGOOGLE_CLOUD_QUOTA_PROJECT, puis la valeur écrite dans le fichier ADC pargcloud auth application-default set-quota-project. Le principal a besoin deserviceusage.services.usesur ce projet.
Emprunter une identité dans le code
Un programme qui tourne sous une identité et doit agir sous une autre (un outil d'administration, un traitement multi-projets) emprunte le compte de service cible au lieu d'en télécharger la clé. Il faut roles/iam.serviceAccountTokenCreator sur le compte cible et l'API IAM Service Account Credentials activée.
from google.auth import impersonated_credentials
from google.cloud import storage
source, _ = google.auth.default()
cible = impersonated_credentials.Credentials(
source_credentials=source,
target_principal="app-sa@PROJECT_ID.iam.gserviceaccount.com",
target_scopes=["https://www.googleapis.com/auth/cloud-platform"],
lifetime=3600, # secondes, une heure au plus par défaut
)
client = storage.Client(project="PROJECT_ID", credentials=cible)
delegates=[...] décrit une chaîne d'emprunts, chaque maillon ayant le rôle Token Creator sur le suivant. Au-delà d'une heure, et jusqu'à 12 heures, la durée demande la contrainte d'organisation constraints/iam.allowServiceAccountCredentialLifetimeExtension pour ce compte.
Jeton d'identité : appeler Cloud Run, une fonction ou IAP
Un service Cloud Run ou une fonction Cloud Run qui exige l'authentification attend un jeton d'identité OIDC signé par Google, pas un jeton d'accès. Son champ aud (audience) désigne le destinataire ; il vit une heure.
| Destinataire | Audience | En-tête | Rôle de l'appelant |
|---|---|---|---|
| Service Cloud Run, fonction Cloud Run | URL du service (https://SERVICE-HASH-REGION.a.run.app), ou une audience personnalisée déclarée sur le service |
Authorization: Bearer, ou X-Serverless-Authorization si l'application utilise déjà Authorization |
roles/run.invoker |
| Ressource derrière IAP | ID client OAuth 2.0 utilisé par IAP | Authorization: Bearer, ou Proxy-Authorization: Bearer |
IAP-secured Web App User |
L'URL du service reste l'audience même pour un appel vers une URL d'étiquette de trafic ; un domaine personnalisé ne peut pas servir d'audience. Le schéma service à service est toujours le même : chaque service appelant a son compte de service attaché, qui reçoit roles/run.invoker sur le seul service appelé, et obtient ses jetons par le serveur de métadonnées.
from google.auth.transport.requests import AuthorizedSession, Request
from google.oauth2 import id_token
AUDIENCE = "https://facturation-abc123-ew.a.run.app"
# Identifiants qui produisent des jetons d'identité et se renouvellent seuls
jetons = id_token.fetch_id_token_credentials(AUDIENCE, request=Request())
facturation = AuthorizedSession(jetons) # créée une fois par processus
r = facturation.post(f"{AUDIENCE}/factures", json={"client": "C-42"}, timeout=30)
id_token.fetch_id_token(Request(), AUDIENCE) renvoie directement la chaîne du jeton, sans cache. fetch_id_token_credentials lit une clé ou un emprunt désignés par GOOGLE_APPLICATION_CREDENTIALS, sinon le serveur de métadonnées ; il ne sait pas produire de jeton d'identité à partir d'identifiants d'utilisateur ni du fichier ADC par défaut. Sur un poste, on emprunte donc un compte de service :
def identifiants_id_token(audience: str):
creds, _ = google.auth.default()
if isinstance(creds, impersonated_credentials.Credentials): # ADC local par emprunt
return impersonated_credentials.IDTokenCredentials(creds, target_audience=audience, include_email=True)
return id_token.fetch_id_token_credentials(audience, request=Request())
En ligne de commande, gcloud auth print-identity-token --impersonate-service-account=app-sa@PROJECT_ID.iam.gserviceaccount.com --audiences=AUDIENCE donne le même jeton pour un test curl. Avec Workload Identity Federation, le jeton d'identité s'obtient de la même façon : impersonated_credentials.Credentials avec les identifiants fédérés comme source, puis IDTokenCredentials.
Vérifier un jeton reçu
Quand Cloud Run contrôle l'accès par IAM, le jeton est vérifié avant d'atteindre le conteneur. Un service qui reçoit les appels sans ce contrôle (service public, push Pub/Sub, tâche Cloud Tasks, Cloud Scheduler) vérifie lui-même signature, émetteur, expiration et audience, puis l'identité de l'appelant :
import cachecontrol, requests
from google.oauth2 import id_token
from google.auth.transport.requests import Request
# Sans cache HTTP, chaque vérification retélécharge les certificats publics de Google
_requete = Request(session=cachecontrol.CacheControl(requests.Session()))
def appelant(en_tete_authorization: str) -> str:
jeton = en_tete_authorization.removeprefix("Bearer ")
infos = id_token.verify_oauth2_token(jeton, _requete, audience="https://SERVICE-HASH-REGION.a.run.app")
if not infos.get("email_verified") or infos["email"] != "pubsub-push@PROJECT_ID.iam.gserviceaccount.com":
raise PermissionError("Appelant non autorisé")
return infos["email"]
verify_oauth2_token lève ValueError sur un jeton invalide ou expiré. Derrière IAP, l'application vérifie l'en-tête x-goog-iap-jwt-assertion avec id_token.verify_token(jwt, Request(), audience=AUDIENCE_IAP, certs_url="https://www.gstatic.com/iap/verify/public_key") ; l'audience vaut /projects/PROJECT_NUMBER/locations/REGION/services/SERVICE pour Cloud Run, /projects/PROJECT_NUMBER/global/backendServices/SERVICE_ID derrière un load balancer.
Durée de vie et renouvellement
- Un jeton d'accès vit une heure, un jeton d'identité aussi. Les objets
Credentialsle conservent (token,expiry,valid) et se renouvellent seuls avant chaque requête dès qu'il reste moins de 3 min 45 s de validité. - Un client ou une
AuthorizedSessioncréés une fois par processus portent ce cache.credentials.refresh(Request())ne s'appelle à la main que pour extrairecredentials.tokenà destination d'un outil qui n'accepte qu'une chaîne. - Obtenir un jeton neuf à chaque requête ajoute un aller-retour vers le serveur de métadonnées ou vers IAM, et consomme le quota de l'API IAM Service Account Credentials en cas d'emprunt.
| Situation | Code |
|---|---|
| Appeler une API Google avec une bibliothèque cliente | storage.Client(project="PROJECT_ID") : ADC implicite |
| Appeler une API Google en REST | AuthorizedSession(google.auth.default(scopes=[...])[0]) |
| Agir sous un autre compte de service | impersonated_credentials.Credentials(source_credentials=..., target_principal=...) |
| Appeler un service Cloud Run ou une fonction | AuthorizedSession(id_token.fetch_id_token_credentials(URL, Request())) |
| Même appel depuis un poste | ADC par emprunt, puis impersonated_credentials.IDTokenCredentials |
| Appeler une ressource IAP | Comme Cloud Run, avec l'ID client OAuth comme audience |
| Authentifier un appel reçu (push, tâche, service public) | id_token.verify_oauth2_token(jeton, Request(), audience=...) puis contrôle de email |
| Charge hors de Google Cloud | Fichier de fédération (gcloud iam workload-identity-pools create-cred-config) dans GOOGLE_APPLICATION_CREDENTIALS, code inchangé |
Pièges
- Mauvaise audience. Un jeton destiné à l'URL d'un autre service ou à un domaine personnalisé est refusé. L'audience est l'URL du service appelé, et la vérification côté serveur doit la fixer : sans
audience=,verify_oauth2_tokenaccepte un jeton émis pour n'importe quel service. - Jeton d'accès envoyé à Cloud Run. Cloud Run attend un jeton d'identité ;
credentials.tokend'identifiants obtenus pargoogle.auth.default()est un jeton d'accès, fait pour les APIgoogleapis.com. - Jeton dans les journaux. Ne jamais journaliser l'en-tête
Authorization,credentials.tokenni une URL qui porte un jeton ; un jeton volé reste valable jusqu'à son expiration. Journaliser l'emailet lesubextraits après vérification. - Clé téléchargée « pour aller plus vite ». Une clé de compte de service copiée sur un poste ou dans une image contourne tout ce qui précède. Sur un poste :
gcloud auth application-default login --impersonate-service-account=...; en CI : fédération (voir Déployer sans clé). - Scopes d'une VM. Sur une VM Compute Engine, les access scopes de l'instance plafonnent le jeton du compte attaché : une instance restreinte obtient
403 ACCESS_TOKEN_SCOPE_INSUFFICIENTmalgré les bons rôles. Donner le scopecloud-platformà l'instance et régler les droits par IAM. gcloud auth loginne suffit pas. Le code lit ADC, pas les identifiants de la CLI :DefaultCredentialsErrorsur un poste où seulgcloud auth logina été fait.