OAuth 2.0 et SSO OpenID Connect

Le flux OAuth 2.0 Authorization Code est le flux recommandé et le plus sécurisé pour la plupart des applications, y compris les applications web et les applications monopages (SPA). Il utilise PKCE (Proof Key for Code Exchange) pour les clients publics afin de prévenir les attaques par interception du code d'autorisation.

Idéal pour : Applications web, SPA, applications mobiles, intégrations tierces

Utilisez les refresh tokens pour obtenir de nouveaux access tokens sans exiger une nouvelle connexion de l'utilisateur. Les refresh tokens sont valables 14 jours et peuvent être renouvelés pour maintenir la sécurité.

Idéal pour : Sessions longue durée, services en arrière-plan, accès hors connexion

Le flux OAuth 2.0 Resource Owner Password Credentials est pris en charge pour la compatibilité ascendante avec les intégrations existantes. Les nouvelles intégrations doivent utiliser l'Authorization Code Flow à la place.

Idéal pour : Applications existantes, outils internes (déconseillé pour les nouveaux développements)

GET /connect/authorize

Lance le flux d'autorisation OAuth. Redirige l'utilisateur pour qu'il se connecte via son fournisseur d'identité (Microsoft, Google, ou email/mot de passe).

Paramètres de requête :

• client_id (obligatoire): L'identifiant de votre application
• redirect_uri (obligatoire): URL de redirection après authentification
• response_type (obligatoire): Doit être 'code'
• scope (obligatoire): Liste de scopes séparés par des espaces (openid, email, profile, offline_access, roles)
• code_challenge (obligatoire pour les SPA): Code challenge PKCE
• code_challenge_method (obligatoire avec code_challenge): 'S256'
• state (recommandé): Chaîne aléatoire pour prévenir les attaques CSRF
• tenant_id (facultatif): Tenant spécifique dans lequel s'authentifier

POST /connect/token

Échange un code d'autorisation contre des access tokens, un ID token, et un refresh token facultatif.

Format de la requête : application/x-www-form-urlencoded

Paramètres :

• grant_type (obligatoire): 'authorization_code', 'refresh_token', ou 'password'
• code (obligatoire pour le flux authorization code): Code d'autorisation obtenu via /authorize
• client_id (obligatoire): L'identifiant de votre application
• client_secret (obligatoire): Le secret de votre application (à garder confidentiel)
• redirect_uri (obligatoire): Doit correspondre à la requête /authorize
• code_verifier (obligatoire pour les SPA): Code verifier PKCE
• refresh_token (pour le flux de rafraîchissement): Le refresh token à échanger
• username & password (pour le flux password): Identifiants de l'utilisateur

POST /connect/introspect

Valide et inspecte le contenu d'un access token ou d'un refresh token.

GET /.well-known/openid-configuration

Point de terminaison de métadonnées OIDC standard. Retourne les informations de découverte, notamment les points de terminaison, les clés publiques, les scopes pris en charge et les grant types.

Créez un code verifier et un code challenge côté client :

// 1. Generate random code verifier (43-128 characters)
const codeVerifier = generateRandomString(128);

// 2. Create code challenge via SHA256 hash
const codeChallenge = await crypto.subtle.digest('SHA-256',
  new TextEncoder().encode(codeVerifier)
);

// 3. Base64-URL encode the challenge
const codeChallengeB64 = base64UrlEncode(codeChallenge);

// Store codeVerifier in sessionStorage for Step 3
sessionStorage.setItem('pkce_verifier', codeVerifier);

Dirigez l'utilisateur vers la connexion :

GET /connect/authorize?
  client_id={your_app_id}
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=openid email profile
  &code_challenge={pkce_challenge}
  &state={random_state}

L'utilisateur sera redirigé vers son fournisseur d'identité (Microsoft, Google, ou email/mot de passe), procédera à l'authentification, puis sera redirigé vers votre redirect_uri avec un code d'autorisation.

Depuis votre backend, échangez le code d'autorisation :

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={auth_code}
&client_id={your_app_id}
&client_secret={your_app_secret}
&redirect_uri=https://your-app.com/callback
&code_verifier={pkce_verifier}

En cas de succès, vous recevez :

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "DefxA1234567890...",
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Validez la signature de l'ID token à l'aide de la clé publique issue de /.well-known/openid-configuration, vérifiez les claims issuer et audience, puis extrayez les informations de l'utilisateur.

L'ID token (JWT) contient les informations d'identité de l'utilisateur :

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@company.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "iss": "https://api.advanza.ai",
  "aud": "your_app_id",
  "iat": 1234567890,
  "exp": 1234571490
}

Claims principaux :

• sub: Identifiant unique de l'utilisateur (Guid)
• email: Adresse email de l'utilisateur
• email_verified: Indique si l'email est vérifié
• name, given_name, family_name: Nom de l'utilisateur
• tenant_id: Tenant/organisation actif de l'utilisateur
• iss: Émetteur du token (toujours https://api.advanza.ai)
• aud: Audience visée (l'identifiant de votre application)
• iat: Date d'émission du token (timestamp Unix)
• exp: Expiration du token (timestamp Unix)

L'access token (JWT) contient les informations d'autorisation :

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@company.com",
  "name": "John Doe",
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "roles": ["Owner"],
  "scope": "openid email profile offline_access roles",
  "iss": "https://api.advanza.ai",
  "aud": "your_app_id",
  "iat": 1234567890,
  "exp": 1234571490
}

Claims principaux :

• sub: ID de l'utilisateur
• email, name: Informations de l'utilisateur
• tenant_id: Tenant actif (à utiliser pour le routage multi-tenant)
• roles: Rôles de l'utilisateur au sein du tenant
• scope: Scopes accordés
• exp: Expiration (généralement 1 heure)

Utiliser l'access token pour : À inclure dans l'en-tête Authorization (Authorization: Bearer {access_token}) lors des appels aux API Advanza ou à votre backend.

Lors de la première connexion, l'utilisateur se voit attribuer un tenant par défaut. Le claim tenant_id sera renseigné avec l'ID de ce tenant.

Les utilisateurs membres de plusieurs tenants peuvent en changer en transmettant le paramètre tenant_id souhaité au point de terminaison d'autorisation :

GET /connect/authorize?
  client_id={your_app_id}
  &redirect_uri=https://your-app.com/callback
  &response_type=code
  &scope=openid email profile
  &tenant_id=12345678-1234-1234-1234-123456789012
  &code_challenge={pkce_challenge}

Utilisez le claim tenant_id pour router les requêtes vers le bon contexte de tenant dans votre backend :

// Extract tenant from token claims
const tenantId = tokenClaims.tenant_id;

// Route request to tenant context
const tenantContext = getTenantContext(tenantId);
const result = await performAction(tenantContext, action);