Google Cloud Marketplace Sign-Up: Verify the JWT

Google Cloud Marketplace sign-up is the step where a buyer who has bought your SaaS product registers with you: Google posts a signed JSON Web Token to your sign-up URL, the token is verified and the buyer linked to an account, and the account Google created for them has to be approved before a private offer can take effect. Miss an approval by the offer’s scheduled start date, and the offer is automatically rejected.

---

Acme is about to send its first Google Cloud Marketplace private offer to Umbrella, and its security reviewer has one item left: the sign-up path. What does Google send to our sign-up page? What must we verify and approve? And how do we stop someone binding their own account to another customer’s purchase?

Google’s partner documentation answers the first two. The third depends on what reaches your page: Google’s token if you integrate directly, or a Fours redirect if Fours receives the buyer first. This runbook covers verify, approve and bind, then the cut-over to Fours’ Signed Buyer Handoff. The AWS counterpart, a registration page that redeems a token through ResolveCustomer, is in the AWS Marketplace SaaS registration page checklist.

What does Google send to your sign-up URL?

When a buyer starts Google Cloud Marketplace sign-up, Google sends an HTTP POST request to your sign-up page with a JSON Web Token in the x-gcp-marketplace-token parameter. The buyer starts it from the Register with button that carries your company name, if they don’t have an account in your system yet.

A JSON Web Token (JWT) is a compact set of claims, signed so the receiver can check who issued it. Google’s carries “the user’s procurement account ID, which identifies them as a Google Cloud user, and an obfuscated ID, which represents their Google account ID.” Google’s rule for them: “You must use both the procurement account ID and the obfuscated ID to link the user’s Google account to their account in your system.”

Three details shape the page:

• No login wall. Users must reach the sign-up page “without first entering a username and password.”
• Procurement accounts aren’t people. “It’s possible for a single user to have multiple procurement account IDs, or for multiple users to share a common procurement account ID,” so don’t model the link as one-to-one.
• Sign-up isn’t the only POST. When customers log in with SSO, Google posts a token “of the same format” to your login page.

Event	Request	Verify the JWT?
Sign up a new customer	POST	Yes
Customer login, without SSO	GET	No
Customer login, with SSO	POST	Yes

Both addresses go in Producer Portal: on your product’s Overview page, under Technical integration, choose Frontend integration and fill in Sign up URL and Login URL.

Which claims are in Google’s sign-up JWT?

Google’s token is signed with RS256 and carries its issuer, its issue and expiry times, your product’s domain as the audience, and the buyer’s identifiers and roles. The header’s alg “is always RS256,” and its kid is the key ID you look up in the JSON object at the iss URL.

Claim	What Google’s page says
iss	https://www.googleapis.com/robot/v1/metadata/x509/[email protected], a URL that “links to a public key from Google”
iat	The time the token is sent
exp	”Set to 5 minutes after the token is sent”
aud	”The domain that hosts your product”
sub	One of two readings, below
google.roles	account_admin or project_editor
google.user_identity	”An obfuscated user reference,” usable as a login_hint to start a Google sign-in
google.orders	Only with multiple orders of the same product turned on: an order ID for each entitlement, which your login page must be able to handle

Google’s page gives sub two meanings. Its payload template shows "sub": "PROCUREMENT_ACCOUNT_ID", while the bullet under it says “sub is the user’s Google account ID.” The page doesn’t reconcile them, so don’t build on either reading alone. Google’s earlier rule holds either way: link on both IDs. Our suggestion is to store sub and google.user_identity side by side with the account.

Roles tell you who is registering. account_admin marks “a Billing Account Administrator (Order Administrator) of the billing account that purchased the product”; project_editor, “an Editor (Entitlement Manager), but not a Billing Administrator, of the project under that billing account.” With SSO on, account_admin users must also have project_editor.

What must you verify before trusting Google’s token?

Google lists five checks: the signature against Google’s public key, exp, aud, iss, and a non-empty sub. When you receive the token, Google says you must verify:

1. The signature, “using the public key from Google,” found through kid and the iss URL.
2. Expiry, “by checking the exp claim”: five minutes after sending.
3. Audience: aud “is the correct domain for your product.”
4. Issuer: iss is exactly the cloud-commerce-partner@system.gserviceaccount.com URL in the table above.
5. Subject: “sub is not empty.”

One thing not to check: “you shouldn’t consider a JWT invalid just because it contains new fields that you haven’t yet encountered,” because Google might add some.

Then: “After verifying the JWT, your sign up page must send an account approval request to the Partner Procurement API.” Google doesn’t say what to do with a token that fails a check. Our reading: treat it as no sign-up at all, so create nothing, link nothing and send no approval.

These checks fall to you only when Google’s POST reaches your own page. With Fours in front, it reaches Fours instead.

Why does the buyer’s account need the signup approval?

Because Google creates the buyer’s account with a pending approval named signup, and a private offer can’t take effect until it’s approved. Cloud Marketplace creates the account resource at a user’s first purchase of your product and reuses it for later ones. Accounts are created ACCOUNT_ACTIVE, “but they have a PENDING entry in the approvals field called signup, which indicates that the user has not yet signed up.”

After the user signs up, “your app must call the Partner Procurement API and indicate that the account has been approved,” at https://cloudcommerceprocurement.googleapis.com/:

POST v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID:approve {'approvalName': 'signup'}

USER_ACCOUNT_ID is “the account ID created by Cloud Marketplace,” also sent in the account Pub/Sub message if you’ve turned on account notifications. A GET on the same account path returns the signup approval, whose state reads APPROVED once it’s done.

The deadline is the offer’s start date. Google’s note for sellers using automatic offer approval: “you still must approve your customer’s account before an offer can take effect. If you don’t approve your customer’s account before the scheduled start date of their offer, that offer is automatically rejected, for both new offers and amendments to existing offers.”

Without automatic offer approval, the entitlement carries the same deadline, a step of its own in renewing a Google Cloud Marketplace private offer. And if you can’t approve an entitlement, Google says to “verify that you’ve approved the customer’s account resource.”

Our suggestion: before every private offer’s scheduled start date, read the buyer’s account and confirm signup reads APPROVED, whichever part of your stack sends the approval.

What does Fours change in the sign-up flow?

With Fours in front, Google’s POST goes to a Fours endpoint: Fours verifies Google’s signed token, creates the entitlement and redirects the buyer to your own sign-up page. You route the sign-up and SSO login URLs in Producer Portal’s Frontend integration through Fours’ endpoints, and put your own page in the product’s Fulfillment URL in the Fours Console.

By default, the redirect carries plain query parameters:

• sugerEntitlementId: the entitlement’s ID in Fours, or a comma-separated list for a buyer with several orders.
• partner: gcp.
• gcpAccountId: the buyer’s Google Cloud Marketplace account ID.
• offerType: such as PRIVATE, or DEFAULT for the public offer.

Your app stores the ID with the buyer’s account and uses it to fetch the entitlement and buyer from the Fours API. Unlike on AWS, there’s no provisional offer to correct later: on Google Cloud, Fours “resolves the subscription synchronously while the buyer is on the landing page.”

The weak point is the ID. Fours’ docs say so plainly: “By default that ID is the only thing your page has to go on — and it is not a secret. It appears in browser history, support tickets, forwarded confirmation emails and webhook logs. Anyone who obtains one can open your signup page with it and bind their account to someone else’s purchase.”

How does Signed Buyer Handoff stop a copied link?

Signed Buyer Handoff is a Fours setting for Google Cloud Marketplace integrations that replaces the plain parameters with a short-lived token only Fours can produce. It’s “opt-in per integration and off by default,” under Integrations → GCP → Edit. When it’s on, sugerEntitlementId, gcpAccountId and offerType leave the URL and move inside the token:

Before: https://app.acme.example/gcp-signup?sugerEntitlementId=ENTITLEMENT_ID&partner=gcp&gcpAccountId=ACCOUNT_ID&offerType=PRIVATE
After:  https://app.acme.example/gcp-signup?token=SIGNED_TOKEN&partner=gcp

Your page verifies the token before trusting any of it, so knowing an entitlement ID no longer makes someone the buyer.

	Google’s sign-up JWT	Fours’ handoff token
Arrives	In the POST, as x-gcp-marketplace-token	In the redirect URL, as token
Lifetime	5 minutes	5 minutes
Keys	Google’s, through the iss URL and kid	Fours’ handoff keys, at /public/handoff/jwks.json
iss	Google’s cloud-commerce-partner service account URL	https://apiv2.suger.cloud
aud	The domain that hosts your product	The host Fours redirects the buyer to
Fifth check	sub isn’t empty	scenario is exactly seller_handoff

Check Fours’ token in five steps, then read ent, buyer, product, org, gcp_account, partner and offer_type from the verified payload, “never by decoding the token without verifying it”:

1. Signature, against https://apiv2.suger.cloud/public/handoff/jwks.json, fetched once at startup and cached. It’s a dedicated key set, “not the same as the OAuth JWKS at /.well-known/jwks.json.”
2. iss is https://apiv2.suger.cloud in production.
3. exp: the token is less than five minutes old, allowing about 30 seconds of clock skew.
4. aud is “the host Fours actually redirects the buyer to”: normally your Fulfillment URL’s host, or the hook’s host if a BeforeSignupRedirect hook sends buyers elsewhere.
5. scenario is exactly seller_handoff, because “Fours signs other tokens with the same key.”

Three limits to design around:

• It isn’t single-use. “Within those 5 minutes the same token verifies more than once,” so for strict single use, deduplicate on the jti you receive.
• It proves identity, nothing more. It “is not a bearer credential for the Fours API.”
• It’s for the first load. Verify it, establish your own session, and “do not ask the buyer to re-use the link.”

Where JWT verification is awkward, as in Salesforce Apex, you can POST the token and your audience to https://apiv2.suger.cloud/public/handoff/introspect and get the claims back only if all five checks pass, though Fours recommends verifying offline.

In what order should you turn it on?

Ship the verifier first, then flip the toggle. Fours’ docs warn that “if you enable it before your page can read a token, your signup page will reject every buyer,” which turns a security fix into the paid-but-no-access failure in when a buyer pays but provisioning never happens.

1. Ship a handler that reads both forms: verify token when it’s present, and keep handling the plain parameters when it isn’t.
2. Pin the keys, issuer and audience: /public/handoff/jwks.json (refreshing the cache if signatures fail after a key rotation), https://apiv2.suger.cloud, and the host Fours redirects buyers to.
3. Flip the toggle: under Integrations → GCP → Edit, enable Signed Buyer Handoff.
4. Watch the next sign-ups. No token parameter means the toggle is off or that redirect fell back to plain parameters.
5. Add jti deduplication if your flow needs strict single use.

Keep the plain branch after the cut-over. Fours “falls back to unsigned parameters rather than failing a purchase,” and not only during migration: the redirect still carries plain parameters “when the purchase doesn’t resolve to exactly one entitlement, when signing fails, or when your signup URL is the Fours-hosted new-client form.” A purchase that resolves to several entitlements is one of those cases.

For plain arrivals once the toggle is on, our suggestion is to treat the ID as a claim to check, not proof: look it up through the Fours API before attaching it, and if it’s already attached to an account, send the buyer to sign in rather than create a second one.

Frequently asked questions

What does Google send to a SaaS sign-up page?

An HTTP POST with a JSON Web Token in the x-gcp-marketplace-token parameter, sent when the buyer clicks Register with your company’s name in Cloud Marketplace. It carries the buyer’s procurement account ID and an obfuscated Google account ID, and expires five minutes after it’s sent.

What must you check in Google’s sign-up JWT?

Google lists five checks: the signature uses Google’s public key, the token hasn’t expired, aud is your product’s domain, iss is Google’s cloud-commerce-partner service account URL, and sub isn’t empty. Don’t reject a token just because it contains fields you haven’t seen before.

What happens if a buyer’s Google Cloud Marketplace account isn’t approved?

Google creates the account with a pending approval named signup. With automatic offer approval on, an account not approved before a private offer’s scheduled start date gets that offer automatically rejected, for new offers and amendments alike. Without it, the entitlement faces the same deadline.

Is the entitlement ID that Fours sends your sign-up page a secret?

No. Fours’ docs say it appears in browser history, support tickets, forwarded confirmation emails and webhook logs, and anyone who obtains one can bind their own account to someone else’s purchase. On Google Cloud Marketplace, Signed Buyer Handoff replaces it with a short-lived signed token.

Is a Signed Buyer Handoff token single-use?

No. A handoff token lasts five minutes and verifies more than once within that window. For strict single use, deduplicate on the token’s jti claim, and start your own session on first load rather than asking the buyer to reuse the link.

Why does a signup redirect arrive without a token?

Either the toggle is off, or Fours fell back to plain parameters rather than fail a purchase, which it does when the purchase doesn’t resolve to exactly one entitlement, when signing fails, or when your signup URL is the Fours-hosted new-client form. Handle both forms.

Takeaways

• Google posts a five-minute, RS256-signed JWT to your sign-up URL. Verify the signature, exp, aud, iss and a non-empty sub, and don’t reject it for new fields.
• Google’s page gives sub two meanings: store sub and google.user_identity together and link on both.
• Every buyer’s account starts with a pending signup approval, and a private offer can’t take effect without it. Under automatic offer approval, an account still unapproved at the scheduled start date gets the offer automatically rejected.
• Through Fours, the default redirect’s entitlement ID isn’t a secret. Signed Buyer Handoff, off by default, replaces it with a five-minute signed token.
• Ship the verifier before you flip the toggle, and keep handling the plain parameters Fours falls back to.

Fours receives your Google Cloud Marketplace buyers, verifies Google’s token, creates each entitlement and, with Signed Buyer Handoff on, hands your sign-up page a token it can verify. For listing, private offers and co-sell, see the complete guide to selling on Google Cloud Marketplace.