API OAuth 2.0 Avancé

Auris fournit des implémentations des spécifications OAuth 2.0 et OIDC avancées pour les scénarios enterprise. Ces fonctionnalités incluent le Device Authorization Flow pour les appareils sans navigateur, le Token Exchange pour l’impersonation et la délégation, les tokens DPoP (Demonstrating Proof of Possession) liés à l’expéditeur, l’authentification CIBA (Client-Initiated Backchannel Authentication) et l’évaluation du risque avec MFA adaptatif.

Toutes les fonctionnalités OAuth 2.0 avancées doivent être activées pour chaque application dans la Console Auris (Console > Applications > [Nom App] > OAuth Avancé) avant de pouvoir être utilisées.

Device Authorization Flow (RFC 8628)

Le Device Authorization Flow permet aux appareils avec des capacités d’entrée limitées (smart TV, terminaux CLI, appareils IoT) d’obtenir des tokens OAuth 2.0. L’appareil affiche un code utilisateur court et une URL ; l’utilisateur complète l’authentification sur un appareil séparé.

Corps de la requête

{
  "client_id": "app_abc123",
  "scope": "openid profile email"
}

Réponse de succès

{
  "ok": true,
  "data": {
    "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://api.altovar.net/hosted/device",
    "verification_uri_complete": "https://api.altovar.net/hosted/device?user_code=WDJB-MJHT",
    "expires_in": 1800,
    "interval": 5
  }
}

Codes d’erreur

Polling pour le Token

Une fois le user_code affiché à l’utilisateur, l’appareil doit effectuer un polling sur l’endpoint token jusqu’à ce que l’utilisateur autorise la demande, que le code expire ou que l’utilisateur refuse l’accès.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "app_abc123"
}

Token Exchange (RFC 8693)

Le Token Exchange permet à un service d’obtenir des tokens en agissant comme un autre utilisateur (impersonation) ou pour le compte d’un autre utilisateur (délégation). Les deux nécessitent des permissions explicites et génèrent des entrées complètes dans le journal d’audit.

Impersonation

Le service demandeur agit entièrement comme l’utilisateur cible. Le token résultant a l’ID de l’utilisateur cible comme sub. Tous les événements d’audit montrent l’impersonation.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "impersonation",
  "target_user_id": "usr_target123"
}

Réponse — token standard avec "sub": "usr_target123"

Délégation

Le service demandeur agit pour le compte de l’utilisateur original. Le sujet original est préservé dans le token. Le claim act identifie le principal qui agit.

{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "exchange_type": "delegation"
}

Payload JWT résultant

{
  "sub": "usr_original123",
  "act": {
    "sub": "usr_acting_service456"
  },
  "scope": "read:data"
}

Champs de la requête

Codes d’erreur

DPoP — Demonstrating Proof of Possession (RFC 9449)

Les tokens DPoP sont cryptographiquement liés au client qui les a obtenus. Contrairement aux tokens Bearer standard, les tokens DPoP ne peuvent pas être utilisés par un attaquant qui les intercepte car les appels API nécessitent une preuve JWT fraîche signée avec la clé privée du client.

Comment Fonctionne DPoP

1. Génération des clés : Le client génère une paire de clés à courbe elliptique (EC P-256 ou RSA). La clé privée ne quitte jamais le client.
2. Création de la preuve : Pour chaque requête, le client crée un JWT de preuve DPoP signé avec la clé privée, incluant la méthode HTTP, l’URL et un jti unique.
3. Binding du token : Le serveur valide la preuve, extrait le thumbprint JWK et lie le token émis à cette clé publique.
4. Appels API : Les appels API suivants nécessitent à la fois le token DPoP et une nouvelle preuve DPoP fraîche pour cette requête spécifique.

Structure de la Preuve DPoP

DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik...

Le JWT de preuve DPoP a la structure suivante :

Header

{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
    "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
  }
}

Payload

{
  "htm": "POST",
  "htu": "https://api.altovar.net/api/auth/token",
  "iat": 1707300000,
  "jti": "unique-id-per-request-abc123",
  "nonce": "server-provided-nonce"
}

Token DPoP dans la Réponse

Lors de l’obtention d’un token avec DPoP, la réponse inclut "token_type": "DPoP" au lieu de "Bearer". Le JWT du token d’accès contient un claim cnf.jkt avec le thumbprint JWK :

{
  "sub": "usr_abc123",
  "cnf": {
    "jkt": "0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"
  }
}

Pour utiliser un token DPoP, inclus l’en-tête Authorization: DPoP <token> ainsi qu’un en-tête DPoP: <fresh-proof>.

Gestion du Nonce

Le serveur peut nécessiter un nonce pour prévenir les replays. Inclus le nonce dans les preuves DPoP suivantes :

DPoP-Nonce: eyJ...server-issued-nonce...

Ce nonce doit être inclus dans le claim nonce de ton prochain JWT de preuve DPoP. Si tu envoies une preuve sans nonce quand il est requis, tu recevras une erreur use_dpop_nonce avec un nonce frais dans l’en-tête de la réponse.

Codes d’erreur

CIBA — Authentification Backchannel (Client-Initiated Backchannel Authentication)

CIBA permet à un service de lancer une authentification en arrière-plan sur un appareil ou canal séparé (comme une notification push mobile) sans rediriger le navigateur. Utile pour les centres d’appel, l’authentification à distance et les applications sur des appareils séparés.

Corps de la requête

{
  "client_id": "app_abc123",
  "client_secret": "app_secret_xyz",
  "scope": "openid profile",
  "login_hint": "[email protected]",
  "binding_message": "Autoriser paiement 50€ à Jane",
  "requested_expiry": 300
}

Réponse de succès

{
  "ok": true,
  "data": {
    "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac9",
    "expires_in": 300,
    "interval": 5
  }
}

Modes de Notification

La façon dont ton service reçoit le résultat de l’authentification dépend du mode CIBA configuré pour l’application :

Polling CIBA

Pour le mode poll, effectue un polling sur l’endpoint token :

{
  "grant_type": "urn:openid:params:grant-type:ciba",
  "auth_req_id": "1c266114-a1be-4252-8ad1-04986c5b9ac9",
  "client_id": "app_abc123",
  "client_secret": "app_secret_xyz"
}

Les réponses de polling fonctionnent de la même façon que le Device Flow : AUTHORIZATION_PENDING, SLOW_DOWN, EXPIRED_TOKEN, ACCESS_DENIED, ou un token de succès.

Codes d’erreur

Évaluation du Risque et MFA Adaptatif

Auris évalue le risque de chaque événement d’authentification en temps réel. Sur la base du score de risque, il peut autoriser la connexion, demander une étape MFA supplémentaire, ou bloquer complètement la tentative d’authentification.

Facteurs de Risque

Chaque facteur contribue à hauteur de 20% au score de risque global :

Niveaux de Risque

Claims JWT ACR et AMR

Les tokens Auris incluent des claims OIDC standard qui décrivent comment l’utilisateur s’est authentifié :

Claim acr (Authentication Context Class Reference)

Claim amr (Authentication Methods References)

Tableau des méthodes utilisées lors de l’authentification : pwd, otp, sms, webauthn, social, magic_link, sso

{
  "sub": "usr_abc123",
  "acr": "urn:auris:acr:mfa",
  "amr": ["pwd", "otp"]
}

API d’Évaluation du Risque

Paramètres de requête

Exemple de réponse

{
  "ok": true,
  "data": [
    {
      "id": "risk_abc123",
      "userId": "usr_xyz789",
      "score": 72,
      "level": "HIGH",
      "factors": {
        "ipReputation": 20,
        "deviceTrust": 0,
        "geoAnomaly": 20,
        "behavior": 12,
        "actionSensitivity": 20
      },
      "actionTaken": "step_up_mfa",
      "ipAddress": "203.0.113.42",
      "country": "FR",
      "city": "Paris",
      "createdAt": "2025-02-18T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "pages": 8
  }
}

Règles de Risque Personnalisées

Tu peux étendre le moteur d’évaluation du risque avec des règles custom qui remplacent ou augmentent le comportement par défaut.

Corps de la requête

{
  "name": "Bloquer les accès depuis des proxies connus",
  "condition": {
    "field": "ipReputation.isProxy",
    "operator": "equals",
    "value": true
  },
  "action": "block",
  "scoreModifier": 50,
  "isActive": true
}

Champs de condition disponibles

Opérateurs disponibles

equals, not_equals, greater_than, less_than, contains, in

Référence des Permissions

Corrélés

• Concept DPoP — Comment fonctionne le binding de clé DPoP
• Concept Device Flow — Device Authorization Flow expliqué
• Concept CIBA — Authentification backchannel
• Concept Token Exchange — Impersonation et délégation
• Utilisation de DPoP — Implémentation des tokens DPoP
• Device Flow — Guide du Device Flow
• CIBA — Configuration de l’authentification backchannel
• Token Exchange — Guide de l’échange de tokens
• OAuth Avancé Admin — Configuration depuis la Console