Auth

Connexion Google (OAuth)

Permettez aux utilisateurs de votre produit (web, mobile, outil interne) de se connecter avec leur compte Google. Ce guide s’applique à toute application branchée sur Kuunda Auth — pas seulement à un scénario de migration.

1. Principe du flux

Google ne parle pas directement à votre front. Kuunda Auth est l’intermédiaire : c’est lui qui reçoit le callback Google, crée ou retrouve l’utilisateur, puis renvoie la session vers votre application.

1. L’utilisateur clique sur Continuer avec Google dans votre app.
2. Le navigateur est redirigé vers Kuunda Auth (/auth/v1/authorize).
3. Kuunda Auth redirige vers Google (écran de consentement).
4. Google rappelle Kuunda Auth sur l’URI de redirection (callback).
5. Kuunda Auth redirige vers votre Site URL / redirectTo avec une session (fragment #access_token=…).

À la fin, l’utilisateur existe dans Auth → Utilisateurs et votre app peut appeler l’API (REST, Storage, etc.) avec le JWT.

2. Les trois URLs (à ne pas confondre)

La plupart des erreurs viennent d’un mélange entre ces adresses. Elles n’ont pas le même rôle.

3. Créer le client OAuth Google

Vous pouvez créer un client neuf, ou réutiliser un client existant (autre backend, ancienne stack, outil interne) : il suffit d’ajouter l’URI Kuunda dans la liste des redirections, à côté des URIs déjà présentes, jusqu’à la bascule complète.

1. Ouvrez Google Cloud → Identifiants.
2. Créez (ou ouvrez) un client de type Application Web — pas Android, iOS ou « application de bureau ».
3. Renseignez un nom lisible (ex. Kuunda — Mon app).
4. Dans URI de redirection autorisés, ajoutez exactement :

   https://api.kuunda-cloud.com/auth/v1/callback

   Si le projet est en Auth dédiée (forfait Enterprise), l’URI peut être :

   https://{ref}.kuunda-cloud.com/auth/v1/callback

5. Dans Origines JavaScript autorisées, ajoutez au minimum :
   • https://api.kuunda-cloud.com — Auth partagée
   • https://app.kuunda-cloud.com — bouton Tester de la console
   • https://{ref}.kuunda-cloud.com — API via le sous-domaine projet
   • L’origine de votre front : https://app.exemple.ci, et http://localhost:3000 en local
6. Enregistrez, puis copiez le Client ID et le Client secret.

L’écran de consentement Google (marque, domaines, utilisateurs de test en mode « Testing ») doit être publié ou, en développement, votre compte Google doit figurer parmi les testeurs.

4. Configurer le projet Kuunda

Dans la console : https://app.kuunda-cloud.com → votre projet → Auth → Providers.

URLs du projet

Carte URL du site / redirections:

• Site URL — origine qui recevra la session après login. Exemples : http://localhost:3000/, https://app.exemple.ci/, ou https://app.kuunda-cloud.com/ pour tester depuis le dashboard.
• Redirect URLs — toutes les origines que vous passerez en redirectTo (une par ligne). Incluez localhost et la prod.

Activer Google

1. Déplier la carte Google.
2. Cocher Activer Google.
3. Coller le Client ID et le Client secret.
4. Vérifier l’alerte URI de redirection: la même valeur doit figurer dans Google Cloud.
5. Enregistrer — le badge passe à Activé.

5. Tester

1. Ouvrez une fenêtre de navigation privée (évite un compte Google déjà lié par erreur).
2. Dans la console Kuunda, bouton Tester sur la carte Google — ou lancez le flux depuis votre app (section suivante).
3. Choisissez un compte Google et acceptez les permissions.
4. Vous devez atterrir sur la Site URL avec un fragment #access_token=… (et en général refresh_token).
5. Dans Auth → Utilisateurs, l’utilisateur apparaît (e-mail Google, identité custom:proj-{ref}-google).

6. Intégrer dans votre application

Utilisez le SDK @kuunda/kuunda-js. URL du projet et clé anon: Paramètres → API dans la console. N’exposez jamais la clé service_role dans le navigateur.

Initialiser le client

import { createClient } from '@kuunda/kuunda-js';

const kuunda = createClient(
  'https://{ref}.kuunda-cloud.com',
  'kuunda_anon_…',
  { projectRef: '{ref}' }
);

Bouton « Continuer avec Google »

await kuunda.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'https://app.exemple.ci/auth/callback',
  },
});

En navigateur, cette méthode redirige immédiatement vers Kuunda Auth. redirectTo doit être listé dans les Redirect URLs du projet. projectRef est obligatoire pour que provider: 'google' soit réécrit vers le fournisseur du projet.

Nom du provider (SDK vs HTTP)

Kuunda Auth réserve google, github, facebook, apple, azure, x. Kuunda enregistre donc un fournisseur custom par projet, avec des tirets (identifiant sans underscore).

Sans SDK (HTTP)

Équivalent (sous-domaine projet — apikey optionnel sur cet hôte ; recommandé ailleurs) :

https://{ref}.kuunda-cloud.com/auth/v1/authorize?provider=google&redirect_to=https%3A%2F%2Fapp.exemple.ci%2Fauth%2Fcallback

Forme explicite toujours valide : provider=custom:proj-{ref}-google&apikey=kuunda_anon_…

Après le retour

Kuunda Auth renvoie la session dans le fragment d’URL (#access_token=…&refresh_token=…). Sur la page de destination :

• Lisez kuunda.auth.getSession() si vous avez déjà persisté une session, ou reconstituez-la depuis le hash puis setSession.
• Nettoyez le hash de la barre d’adresse (évite de fuiter le jeton dans l’historique ou les analytics).
• Les appels kuunda.from(…) partent alors avec le JWT ; la RLS s’applique à l’utilisateur Google.

7. Checklist production

• Client OAuth Google en type Application Web, écran de consentement en production (pas « Testing »).
• URI de callback Kuunda enregistrée à l’identique (copier-coller depuis la console, sans slash final).
• Origines JS : domaine de prod + https://api.kuunda-cloud.com ; retirez localhost si vous ne le voulez plus.
• Site URL et Redirect URLs Kuunda pointent vers HTTPS de production.
• Clé anon uniquement dans le front ; secret Google uniquement dans la console Kuunda.
• Si vous aviez déjà un autre callback (ancien hébergeur, autre BaaS), gardez-le jusqu’à validation du cutover, puis retirez-le.

8. Dépannage

Ensuite

• Documentation développeur — clés API, premier SELECT, Auth / Storage / Realtime.
• Kuunda Cloud Managed — Management API, PAT, agents et CI.
• Import de données — si vous basculez un existant (SQL, Auth, fichiers).