Association d'identité : OAuth 2.0

Pour permettre de fluidifier les sessions utilisateur (par exemple, en facilitant l'accès aux avantages fidélité ou aux offres personnalisées) et activer les paiements authentifiés, vous devez implémenter la fonctionnalité d'association d'identité à l'aide d'OAuth 2.0. Si vous n'implémentez pas l'association d'identité, vous devez permettre les expériences invité.

Consultez votre équipe juridique si vous avez des questions concernant les réglementations sur la confidentialité et les pratiques concernant le consentement.

Exigences fondamentales

L'association d'identité utilise OAuth 2.0 pour associer des comptes utilisateur. Votre implémentation OAuth 2.0 doit répondre aux exigences décrites dans Association OAuth.

De plus, pour respecter les best practices de sécurité de Universal Commerce Protocol (UCP), nous vous recommandons vivement d'implémenter une Proof Key for Code Exchange (PKCE) utilisant S256 pour tous les échanges de code d'autorisation, et d'utiliser l'authentification client asymétrique (telle que private_key_jwt ou tls_client_auth) au niveau de votre endpoint de jeton.

Pour en savoir plus, consultez les Consignes générales de UCP.

Niveaux d'accès

Vous devez implémenter les niveaux d'accès suivants, qui accordent l'autorisation pour toutes les opérations du cycle de vie du paiement (création, mise à jour, finalisation) et pour la lecture des données de commande.

dev.ucp.shopping.order:read
dev.ucp.shopping.checkout:manage

Utilisation des jetons

Lorsqu'un utilisateur a associé son compte, Google inclut son jeton d'accès dans l'en-tête HTTP Authorization pour toutes les opérations du cycle de vie du paiement (création, mise à jour, finalisation) et les demandes de données de commande :

Authorization: Bearer <access_token>

Il s'agit du même en-tête que celui utilisé pour l'authentification de machine à machine.

Gestion des erreurs

Lorsqu'une opération nécessitant l'authentification de l'utilisateur échoue en raison d'un problème d'identité, vous devez renvoyer un en-tête de challenge WWW-Authenticate: Bearer conformément à la norme RFC 6750, ainsi que le status code HTTP et le message d'erreur UCP appropriés.

identity_required

Renvoyez cette erreur lorsqu'une opération nécessite l'identité de l'utilisateur, mais que la requête ne contient aucun jeton, ou que le jeton fourni est non valide ou a expiré.

État HTTP : 401 Unauthorized
Code d'erreur UCP : identity_required
WWW-Authenticate : incluez realm="<your-issuer-uri>". Si un jeton est fourni mais qu'il est non valide ou a expiré, incluez également error="invalid_token".

insufficient_scope

Renvoyez cette erreur lorsque la requête contient un jeton d'identité utilisateur valide, mais que celui-ci ne dispose pas des niveaux d'accès requis pour l'opération.

État HTTP : 403 Forbidden
Code d'erreur UCP : insufficient_scope
WWW-Authenticate : incluez realm="<your-issuer-uri>", error="insufficient_scope" et scope="<space-separated list of required scopes>".

Signaler l'association d'identité

Vous devez déclarer la capacité d'association d'identité dans votre profil UCP. Pour obtenir un exemple de la façon de déclarer cette capacité, consultez Profil UCP.

Association simplifiée Google

L'association simplifiée Google est un complément facultatif à la norme OAuth 2.0. Cette solution s'appuie sur des assertions JWT pour combiner les vérifications d'intent et l'échange de jetons sur le endpoint de jeton OAuth 2.0 (intents check, create, get).

Nous vous recommandons d'utiliser l'association simplifiée Google pour offrir une expérience utilisateur fluide. Elle permet aux utilisateurs d'associer des comptes ou d'en créer d'autres à l'aide de leur profil Google sans quitter l'interface Google. Étant donné que le flux se déroule entièrement dans l'interface utilisateur de Google, aucune interface d'association n'est requise. Cela réduit les frais généraux liés au développement, élimine les redirections de navigateur et peut augmenter les taux de conversion.

Spécification : l'implémentation doit respecter les exigences concernant l'association simplifiée.
Normes : bien qu'elle s'appuie sur des concepts de la RFC 7523, cette solution présente des différences visant à renforcer la sécurité.

Métadonnées du serveur d'autorisation (exemple JSON)

Vous devez publier les métadonnées de votre serveur d'autorisation à l'adresse suivante :

GET https://YOUR_DOMAIN/.well-known/oauth-authorization-server

Voici un exemple de ce à quoi cela pourrait ressembler :

{
  "issuer": "https://merchant.example.com",
  "authorization_endpoint": "https://merchant.example.com/oauth2/authorize",
  "token_endpoint": "https://merchant.example.com/oauth2/token",
  "revocation_endpoint": "https://merchant.example.com/oauth2/revoke",
  "scopes_supported": [
    "dev.ucp.shopping.order:read",
    "dev.ucp.shopping.checkout:manage"
  ],
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic"
  ],
  "service_documentation": "https://merchant.example.com/docs/oauth2"
}

Présentation du panier