Identity Linking - OAuth 2.0  |  Google Universal Commerce Protocol (UCP) Guide  |  Google for Developers (original) (raw)

To enable seamless user sessions (e.g., accessing loyalty benefits, personalized offers) and authenticated checkouts, you must implement the Identity Linking capability using OAuth 2.0. If you do not implement identity linking, you must support guest checkout.

Consult with your legal team on any questions regarding privacy regulations and consent practices.

Core Requirements

• Protocol: Implement the OAuth 2.0 Authorization Code flow(RFC 6749 2.3.1).
• Client Authentication: Must support HTTP Basic Authentication (client_secret_basic) at the Token Endpoint.
• Scopes: You must support the standard UCP scopes defined in this section.
• Discovery: You must host a metadata file at/.well-known/oauth-authorization-server(RFC 8414) to allow the Platform to discover your endpoints.

Scopes

You must implement the following scope, which grants permission for all checkout lifecycle operations (Get, Create, Update, Delete, Cancel, Complete).

• Scope Name: ucp:scopes:checkout_session

User Experience: You should present requested scopes as a single, bundled consent screen (e.g., "Allow Google to manage your checkout sessions") rather than granular technical toggles.

Google Streamlined Linking

Google Streamlined Linking is an optional addition to standard OAuth 2.0. It leverages JWT assertions to combine intent checks and token exchange on the OAuth 2.0 token endpoint (check, create, get intents).

Google Streamlined Linking is recommended for a seamless user experience. It allows users to link accounts or create new accounts using their Google profile without leaving the Google interface. Because the flow occurs entirely within Google's UI, a linking frontend is not required. This reduces development overhead, eliminates browser redirects, and can increase conversion rates.

• Specification: Implementation must follow the Requirements for Streamlined Linking.
• Standards: While it draws concepts fromRFC 7523, it differs to enhance security.

You must publish this JSON object athttps://[your-domain]/.well-known/oauth-authorization-server

Example:

{
  "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": [
    "ucp:scopes:checkout_session"
  ],
  "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"
}