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 de l'identité à l'aide d'OAuth 2.0. Si vous n'implémentez pas l'association de l'identité, vous devez prendre en charge 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 de l'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 bonnes pratiques de sécurité de l'Universal Commerce Protocol (UCP), nous vous recommandons vivement d'implémenter la clé de vérification pour l'échange de code (PKCE) à l'aide de 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 point de terminaison de jeton.

Pour en savoir plus, consultez les Consignes générales de l'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 défi WWW-Authenticate: Bearer conformément à la norme RFC 6750, ainsi que le code d'état 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 de l'identité

Vous devez déclarer la capacité d'association de l'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 point de terminaison 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"
}