Integrating Your Application's Frontend

This page describes the steps to integrate your app's frontend with Google Cloud Marketplace. The frontend integration helps give your customers a smooth experience when they go from Google Cloud Marketplace to your app.

Creating an account activation page for new users

When users choose your solution from Google Cloud Marketplace, they must activate their accounts in your app. You must create an activation page to set up and approve users' accounts in your system. You can set up the page as a registration page where users must sign up for an account in your system, or as a page that approves accounts automatically.

In Google Cloud Marketplace, when users click the link to sign up for your app, Google sends an HTTP POST request to your activation page, and sends a JSON Web Token (JWT) in the x-gcp-marketplace-token parameter. The JWT contains the user's procurement account ID, which identifies them as a Google Cloud user. You must use this ID to link the user's Google account to their account in your system.

After verifying the JWT, your activation page must send an account approval request to the Procurement API, described in the backend integration steps.

If you are new to JWT, see the JWT introduction.

Verifying the JWT

The JWT payload is in the following format:

Header

{
  "alg": "RS256",
  "kid": "KEY_ID"
}

Where:

  • alg is always RS256
  • kid indicates the key ID that was used to secure the JWT. Use the key ID to look up the key from the JSON object in the iss attribute in the payload.

Payload

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID"
  }
}

Where:

  • sub is the user's Google account ID. You must use this ID to link the user's Google account to their account in your system.
  • iss identifies the sender of the JWT. The URL in the iss claim links to a public key from Google.
  • exp indicates when the token expires, and is set to 5 minutes after the token is sent.
  • aud is the domain that hosts your solution, such as example-pro.com.

When you receive the JWT, you must verify the following:

  1. Verify that the JWT signature is using the public key from Google.

  2. Verify that the JWT has not expired, by checking the exp claim.

  3. Verify that aud claim is the correct domain for your solution.

  4. Verify that the iss claim is https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com

  5. Verify that sub is not empty.

Integrate single sign-on (SSO) for your customers

When customers sign up for your solution, they must be able to sign in to your application without entering a different username and password.

The SSO integration uses JSON Web Tokens (JWT) to authenticate users. If you are new to JWT, see the JWT introduction.

To set up the SSO integration:

  • Add the URL for your dashboard or web interface to your solution in Partner Portal, in the Plans and Features section.

  • In your application's web interface, add code to verify the JWT payload that is sent to your application when users sign in from Google Cloud Marketplace.

    The format of the JWT for authentication is the same as the JWT sent when users first sign up for your application, described in Verifying the JWT.