Integrating your app's frontend

Stay organized with collections Save and categorize content based on your preferences.

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 Producer Portal

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

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.

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.

Integrating 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.

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 Login 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.

Provisioning service accounts for your customers

If your app requires a service account, you can work with a partner engineer to provision service accounts for your customers and to set up a page for your customers to grant the required Identity and Access Management (IAM) roles to the service accounts. You must provide the link to the page, usually through your app's management console.

To provision the service accounts, contact your partner engineer and include the following information:

  • Service name: This is a unique product ID that differentiates your app from other products. We recommend using the service name created when you onboarded your app.

  • Project ID: The ID of the project in which you create the service accounts that access your customers' resources. All service accounts you app uses must be created in a single project.

  • IAM roles and reasoning: The IAM roles required for the service accounts and the reason why the roles are necessary. This is shared with your customer and can impact whether your customer grants access to the service account.

If you want your customer to return to your site after they grant access to the service account, send the domain name of your console to your partner engineer. You can send multiple domain names, including subdomains, such as staging.example.com.

The partner engineer creates a page to allow your customers to grant access to the service accounts. You then link to the page from your console.

Integrating the URL in your console

Once your partner engineer has notified you that the page is ready, add parameters to the URL, and then link to the page from your console.

You must add two parameters to the URL:

  • service-name: This is the service name you provided to your partner engineer.

  • service-account-email: This is the email address of the service account you created for your customer. Each customer has a unique service account.

The following example shows a URL with the required parameters:

https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email

You can add additional parameters depending on your customer's needs. For example:

https://console.google.com/marketplace-saas/service-account/service-name/service-account-email;single=true;redirect=https%3A%2F%2Fexample.com

The parameters on the URL indicate that your product requires access to a single Google Cloud project and that the customer can return to your console.

List of URL parameters

The following is a list of the URL parameters that you can send to the grant access page:

ParameterDescription
service-nameThis is required. This is the service name you provided to your partner engineer.
service-account-emailThis is required. This is the email address of the service account you created for your customer.
singleWhen true, this indicates that your product requires access to a single project.
hints=project-id-1Sets the project that you want the service account to access. Use commas to separate projects.
filter=role1Limits the roles granted to the service account to a subset of the roles you provided to your partner engineer. Exclude the roles/ when using the filter.
redirectProvides a link for the customer to return to your management console. The domain name must be registered with your partner engineer to use this parameter.