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 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 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 solutions, click the name of your solution.

  2. On the Overview page of your solution, 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"
  }
}

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 the 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 app without entering a different 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 solution, 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 solution, and choose to EDIT your solution'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.