# ===================================================================
# MEMO : Sécurisation d'un service Cloud Run avec IAP (Identity-Aware Proxy)
# ===================================================================
# 
# Objectif : Ce document résume les étapes et les permissions nécessaires 
# pour sécuriser un service Cloud Run avec IAP, en se basant sur 
# l'expérience acquise avec le service 'internal-launchpad'.
#
# Date : 2025-11-16

# ---
# 1. PRINCIPE FONDAMENTAL ET CONTRAINTE MAJEURE
# ---
#
# L'enseignement le plus important est le suivant :
#
# > L'activation d'IAP directement sur un service Cloud Run (sans Load Balancer)
# > restreint l'accès aux utilisateurs qui font partie de la MÊME organisation 
# > Google Workspace que le projet Google Cloud.
#
# Dans notre cas, le projet 'krow-workforce-dev' appartient à l'organisation 
# 'krowwithus.com'. C'est pourquoi :
#   - 'admin@krowwithus.com' A PU ACCÉDER au service.
#   - 'boris@oloodi.com' N'A PAS PU ACCÉDER au service, même avec les bonnes permissions.
#
# Solution adoptée : Créer des comptes utilisateurs via Google Workspace ou 
# Cloud Identity (qui est gratuit) dans le domaine 'krowwithus.com' pour 
# tous les développeurs et administrateurs qui ont besoin d'accéder aux 
# services internes.

# ---
# 2. PRÉREQUIS INDISPENSABLES
# ---
#
# Avant de commencer, les éléments suivants doivent être configurés pour le projet :
#
# a) APIs Google Cloud activées :
#    - Cloud Run API (`run.googleapis.com`)
#    - Identity-Aware Proxy API (`iap.googleapis.com`)
#    - Cloud Build API (`cloudbuild.googleapis.com`)
#    - Artifact Registry API (`artifactregistry.googleapis.com`)
#
#    Commande pour les activer :
#    gcloud services enable run.googleapis.com iap.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com --project=krow-workforce-dev
#
# b) Écran de consentement OAuth configuré :
#    - IAP utilise OAuth2 pour identifier les utilisateurs. L'écran de consentement est obligatoire.
#    - URL : https://console.cloud.google.com/apis/credentials/consent?project=krow-workforce-dev
#    - Type d'utilisateur : "Interne" est préférable si disponible.
#    - Nom de l'application : Utiliser un nom général (ex: "Krow Workforce Platform").
#
# c) Compte de service IAP existant :
#    - Parfois, ce compte n'est pas créé automatiquement. Il est plus sûr de forcer sa création.
#
#    Commande pour le créer :
#    gcloud beta services identity create --service=iap.googleapis.com --project=krow-workforce-dev

# ---
# 3. LOGIQUE DE CONFIGURATION EN 3 ÉTAPES (AUTOMATISÉE DANS LE MAKEFILE)
# ---
#
# Le processus complet pour sécuriser un service se déroule en 3 étapes séquentielles.
#
# ÉTAPE A : DÉPLOIEMENT SÉCURISÉ DU SERVICE
# -----------------------------------------
# Le service doit être déployé en mode privé, puis IAP doit être activé dessus.
#
# 1. Déployer le service avec l'accès public désactivé :
#    gcloud run deploy <SERVICE_NAME> --image <IMAGE_URI> --no-allow-unauthenticated ...
#
# 2. Activer IAP sur le service :
#    gcloud beta run services update <SERVICE_NAME> --iap ...
#
#
# ÉTAPE B : AUTORISER IAP À APPELER LE SERVICE
# -------------------------------------------
# Une fois IAP activé, le proxy IAP a besoin de la permission d'invoquer (d'appeler) 
# votre service Cloud Run. Cette permission est accordée au compte de service IAP.
#
# Commande :
# gcloud run services add-iam-policy-binding <SERVICE_NAME> \
#   --member="serviceAccount:service-<PROJECT_NUMBER>@gcp-sa-iap.iam.gserviceaccount.com" \
#   --role="roles/run.invoker"
#
#
# ÉTAPE C : AUTORISER LES UTILISATEURS À PASSER LE PROXY IAP
# -------------------------------------------------------
# C'est ici qu'on ajoute les utilisateurs finaux (qui doivent être dans l'organisation).
# Cette commande est spécifique à IAP pour Cloud Run.
#
# Commande :
# gcloud beta iap web add-iam-policy-binding \
#   --resource-type=cloud-run \
#   --service=<SERVICE_NAME> \
#   --member="user:email@krowwithus.com" \
#   --role="roles/iap.httpsResourceAccessor"

# ---
# 4. AUTOMATISATION VIA LE MAKEFILE
# ---
#
# Tout ce processus est géré par la commande `make deploy-launchpad-full`.
#
# a) `deploy-launchpad` s'occupe de l'ÉTAPE A.
#
# b) `configure-iap-launchpad` s'occupe des ÉTAPES B et C.
#
#    - Il lit les utilisateurs depuis `firebase/internal-launchpad/iap-users.txt`.
#    - Il exécute la commande de l'ÉTAPE B pour le compte de service IAP.
#    - Il exécute la commande de l'ÉTAPE C pour chaque utilisateur du fichier.
#
# Pour adapter cela à 'admin-web', il faudra :
# 1. Créer des variables similaires à `CR_LAUNCHPAD_...` pour `admin-web`.
# 2. Créer de nouvelles cibles `deploy-admin-web-full`, `configure-iap-admin-web`, etc., 
#    en copiant la logique de celles du launchpad et en adaptant les noms de service.

# ---
# 5. VÉRIFICATION ET DÉPANNAGE
# ---
#
# a) Lister les utilisateurs autorisés :
#    La commande `make list-iap-users` est le meilleur moyen de vérifier qui a accès.
#
# b) Erreur "You don't have access" :
#    - Cause 1 : L'utilisateur n'est pas dans la bonne organisation (le plus probable).
#    - Cause 2 : L'utilisateur n'est pas dans le fichier `iap-users.txt` et `make configure-iap-launchpad` n'a pas été lancé.
#    - Cause 3 : Problème de cache de navigateur. Toujours tester dans une nouvelle fenêtre de navigation privée.
#    - Cause 4 : Délai de propagation des permissions IAM (attendre 2-3 minutes).
#
# c) Erreur "Forbidden" :
#    - Cela signifie que l'authentification a réussi mais que la permission d'invoquer le service est manquante.
#    - La cause la plus probable est que l'ÉTAPE B (donner la permission au compte de service IAP) a échoué ou a été oubliée.
