Integrating your app'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 product 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. When you set up your activation page, ensure that the users can access the page without entering a username and password.

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 Partner Procurement API, described in the backend integration steps.

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

Adding your account activation page to the portal

You can use Producer Portal or Partner Portal to add your account activation page URL.

Producer Portal

The direct link to Producer Portal is:

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

To add your account activation page to Producer Portal:

  1. In the list of products, click the name of your product.

  2. On the Overview page of your product, go to the Technical Integration section and click on FRONTEND INTEGRATION.

  3. Enter the URL for your account activation page into the Sign up URL field.

Partner Portal

The direct link to Partner Portal is:

https://console.cloud.google.com/partner/solutions?project=YOUR_PROJECT_ID

To add your account activation page to Partner Portal:

  1. In the list of solutions, click the solution ID that you created.

  2. From the Plans & Features page, click to edit the page.

  3. Enter the URL for your account activation page into the Signup URL field.

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",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_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 product, such as example-pro.com.
  • roles is an array of strings representing the user's roles. Right now, it can be either: ** account_admin, which indicates that the user is a Billing Account Administrator of the billing account that purchased the product, or ** project_editor, which indicates that the user is a Project Editor, but not a Billing Administrator, of the project under that billing account.
  • user_identity is the user's obfuscated GAIA ID, which can be used to initiate Open ID Connect.

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 the aud claim is the correct domain for your product.

  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.

Initiating Google sign-in with login_hint

If you want your users to go through an OAuth 2.0 consent flow with your site, you can use the identity information from the payload to initialize that flow on the Google account they were using for Google Cloud before the redirect. To do this, you supply the user_identity provided in the JWT as the login_hint. For more information, visit the Google OAuth2.0 documentation.

After the user completes the OAuth 2.0 flow with your site, you should verify that they are the user you expected to complete the OAuth flow. You do this by using the OAuth 2.0 access token to call the Google UserInfo API to fetch their basic user information. This returns an ID that should match the user_identity field from the JWT.

Integrate single sign-on (SSO) for your customers

When customers sign up for your product, they must be able to register for an account on your activation page without first entering a username and password.

The SSO integration uses JWTs to authenticate users. If you are new to JWT, see the JWT introduction.

You can set up the SSO integration in Producer Portal or Partner Portal:

Producer Portal

To set up the SSO integration:

  1. On the Overview page of your product, go to the Technical Integration section and click on FRONTEND INTEGRATION.

  2. To link to your dashboard, enter the URL for your dashboard into the Dashboard URL field.

  3. To use Google SSO, click Enable SSO login (optional), then enter your SSO login URL into the SSO URL field.

  4. In your app's web interface, add code to verify the JWT payload that is sent to your app 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 app, described in Verifying the JWT.

Partner Portal

To set up the SSO integration:

  1. Go to the Plans and Features page of your product, and choose to EDIT your product's plans and features.

  2. To link your dashboard, enter the URL for your dashboard into the Dashboard URL field.

  3. To use Google SLO, under SSO Login (optional), click to Enable SSO, then enter your SSO login URL into the SSO login URL field. Enter the URL for your SSO API keys into the SSO API Keys URL field.

  4. In your app's web interface, add code to verify the JWT payload that is sent to your app 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 app, described in Verifying the JWT.