アプリのフロントエンドを統合する

このページでは、アプリのフロントエンドを Cloud Marketplace と統合して、お客様が Cloud Marketplace からご使用のプロダクトに切り替える際のスムーズなエクスペリエンスを提供する方法について説明します。

概説すると、ユーザーアカウントの作成を処理するための登録 URL を用意する必要があります。作成後、アカウントはウェブコンソールで管理されます。また、ユーザーがログインするための URL も指定する必要があります。必要に応じて、シングルサインオン（SSO）を統合できます。

Producer Portal を使用したアプリのフロントエンドの統合

アプリのフロントエンドを Cloud Marketplace と統合するために必要なすべての情報に 1 つの場所からアクセスするには、Producer Portal の [フロントエンドの統合] セクションを使用します。

Producer Portal の直接リンクは次のとおりです。

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

[フロントエンドの統合] セクションにアクセスするには:

プロダクトのリストで貴社のプロダクト名をクリックします。
プロダクトの [概要] ページで [技術統合] セクションに移動し、[Frontend integration] をクリックします。

登録用 URL を追加する

ユーザーが Cloud Marketplace からプロダクトを購入する場合は、プロダクト用のアカウントを作成する必要があります。これを行うには、システムでユーザーのアカウントを設定および承認するための登録ページを作成する必要があります。このページは、ユーザーがシステムのアカウントに登録するための登録ページとして、またはアカウントを自動的に承認するページとして設定できます。

登録ページを作成したら、Producer Portal で追加します。

プロダクトのリストで貴社のプロダクト名をクリックします。
プロダクトの [概要] ページで [技術統合] セクションに移動し、[Frontend integration] をクリックします。
登録ページの URL を [登録 URL] フィールドに入力します。

ユーザーの登録情報を確認する

ユーザーがシステムでアカウントを設定していない場合は、Cloud Marketplace で [YOUR_COMPANY_NAME に登録] ボタンをクリックする必要があります。ボタンをクリックすると、Google Cloud から x-gcp-marketplace-token パラメータに JSON ウェブトークン（JWT）が指定された HTTP POST リクエストが送信されます。JWT には、ユーザーの調達アカウント ID が含まれており、Google Cloud ユーザーとして識別されます。また、難読化された ID は、Google アカウント ID を表します。ユーザーの Google アカウントをシステムのアカウントにリンクするには、調達アカウント ID と難読化 ID の両方を使用する必要があります。

JWT を検証した後、バックエンドの統合の手順で説明されているように、有効化ページからアカウント承認リクエストを Partner Procurement API に送信する必要があります。

JWT ペイロードとペイロードの確認方法の詳細については、以下の JWT を確認するをご覧ください。

JWT の使用に慣れていない場合は、JWT の概要をご覧ください。

ログイン URL を追加する

アプリのログインページの URL を指定する必要があります。

Producer Portal 内のアプリのログインページの URL を入力するには:

プロダクトのリストで貴社のプロダクト名をクリックします。
プロダクトの [概要] ページで [技術統合] セクションに移動し、[Frontend integration] をクリックします。
アプリのログインページの URL を [ログイン URL] フィールドに入力します。

（省略可）顧客のシングルサインオン（SSO）を有効にする

Producer Portal で SSO を有効にするには:

プロダクトのリストで貴社のプロダクト名をクリックします。
1. プロダクトの [概要] ページで [技術統合] セクションに移動し、[Frontend integration] をクリックします。
2. [SSO ログインを有効にしますか？] で [はい] を選択します。

顧客の SSO ログイン情報を確認する

お客様が SSO を使用してアプリにログインすると、Google Cloud がユーザーが最初にアプリに登録したときに送信される JWT と同じ形式の JSON ウェブトークン（JWT）とともに HTTP POST リクエストをアプリのログインページに送信します。

JWT ペイロードとペイロードの確認方法の詳細については、以下の JWT を確認するをご覧ください。

JWT を確認する

新規顧客の登録や、SSO を使用してお客様のログインを行う一部のプロセスでは、検証することが必要な可能性のある JSON ウェブトークン（JWT）とともに HTTP POST リクエストを送信します。

次の表に以下の内容の一覧を示します。

JWT を使用して HTTP リクエストを送信するイベント。
関連する HTTP リクエストのタイプ。
JWT を検証する必要があるかどうか。

イベント	HTTP リクエストの種類	JWT 検証が必要
新規顧客を登録する	POST	○
SSO を使用しない顧客ログイン	GET	×
SSO を使用する顧客ログイン	POST	○

JWT ペイロード

JWT ペイロードの形式は次のとおりです。

ヘッダー

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

ここで

alg は常に RS256 です。
kid は JWT を保護するために使用されたキー ID を示します。キー ID を使用して、ペイロード内の iss 属性の JSON オブジェクトからキーを検索します。

ペイロード

{
  "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
  }
}

ここで

sub はユーザーの Google アカウント ID です。この ID を使用して、ユーザーの Google アカウントをシステムのアカウントにリンクする必要があります。
iss は JWT の送信者を識別します。iss クレーム内の URL は Google の公開鍵にリンクします。
exp はトークンの有効期限を示し、トークンが送信されてから 5 分後に設定されます。
aud は、プロダクトをホストするドメインです（example.com など）。
roles は、ユーザーのロールを表す文字列の配列です。次のいずれかです。
- account_admin: ユーザーが、プロダクトを購入した請求先アカウントの請求先アカウント管理者（注文管理者）であることを示します。
- project_editor: ユーザーが、その請求先アカウントに含まれるプロジェクトの編集者（利用資格管理者）であり、課金管理者ではないことを示します。
注: シングルサインオン（SSO）を有効にしている場合は、account_admin ロールを付与するユーザーには project_editor ロールも付与する必要があります。
user_identity は、ユーザーの難読化された GAIA ID です。これを使用して OpenID Connect を起動できます。

同じプロダクトの複数注文のペイロード

同じプロダクトの複数の注文を有効にしている場合、ペイロードには追加の orders オブジェクトが含まれます。これには、各注文の利用資格 ID に対応する一意の注文 ID が含まれます。アプリのログインページがこの新しい orders フィールドに応答できることを確認します。

{
  "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,
    "orders": [ORDER_ID1, ORDER_ID2]
  }
}

ここで

ORDER_ID は、同じプロダクトに対する異なるオファーを示す、各利用資格 ID の一意の注文 ID のリストです。このフィールドは、同じプロダクトの複数の注文が有効になっている場合にのみ使用できます。

同じプロダクトの複数の注文を有効にする場合について詳しくは、同じプロダクトの複数の注文を有効にするをご覧ください。

ペイロードを確認する

JWT を受け取ったら、以下を確認する必要があります。

JWT の署名が Google の公開鍵を使用していることを確認します。
exp クレームを確認して、JWT の有効期限が切れていないことを確認します。
aud クレームがプロダクトの正しいドメインであることを確認します。
iss クレームが https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com であることを確認します
sub が空でないことを確認します。

`login_hint` による Google ログインの開始

ユーザーがサイトで OAuth 2.0 の同意フローを実行する場合は、ペイロードの ID 情報を使用して、リダイレクトの前に Google Cloud で使用していた Google アカウントでフローを初期化します。これを行うには、JWT で提供される user_identity を login_hint として指定します。詳細については、Google OAuth2.0 ドキュメントをご覧ください。

ユーザーがサイトで OAuth 2.0 フローを完了した後は、OAuth フローを完了する必要があるユーザーであることを確認してください。これを行うには、OAuth 2.0 アクセストークンを使用して Google UserInfo API を呼び出し、基本的なユーザー情報を取得します。これにより、JWT の user_identity フィールドと一致すると予想される ID が返されます。

顧客のサービスアカウントを作成する

プロダクトにサービスアカウントが必要な場合は、パートナーエンジニアと協力して以下を行うことができます。

顧客のサービスアカウントをプロビジョニングする。
顧客のサービスアカウント管理ページを設定して、必要な Identity and Access Management（IAM）のロールをサービスアカウントに付与します。

このサービスアカウントページへのリンクを、通常はプロダクトの管理コンソールからお客様に提供する必要があります。

サービスアカウントをプロビジョニングする

サービスアカウントをプロビジョニングするには、パートナーエンジニアに連絡して次の情報を含めます。

サービス名: これは、プロダクトを他のプロダクトと区別する一意のプロダクト ID です。プロダクトをオンボーディングしたときに作成したサービス名を使用することをおすすめします。
プロジェクト ID: お客様のリソースにアクセスするサービスアカウントを作成するプロジェクトの ID。プロダクトで使用するすべてのサービスアカウントは、単一のプロジェクト内に作成する必要があります。
IAM ロールと理由: サービスアカウントに必要な IAM ロールと、そのロールが必要な理由。これはお客様と共有され、お客様がサービスアカウントへのアクセス権を付与するかどうかに影響します。

サービスアカウントにアクセス権を付与した後、顧客をサイトに戻す必要がある場合は、コンソールのドメイン名をパートナーエンジニアに送信します。staging.example.com などのサブドメインを含めて、複数のドメイン名を送信できます。

プロダクトのコンソールにサービスアカウント管理ページを統合する

パートナーエンジニアは、サービスアカウント管理ページを作成して、お客様がサービスアカウントへのアクセス権を付与できるようにします。コンソールからページへのリンクを設定します。

サービスアカウント管理ページの準備が整ったことをパートナーエンジニアから通知されたら、URL にパラメータを追加し、コンソールからページにリンクします。

URL に 2 つのパラメータを追加する必要があります。

service-name: パートナーエンジニアに提供したサービス名です。
service-account-email: お客様用に作成したサービスアカウントのメールアドレスです。お客様ごとに一意のサービスアカウントがあります。

次の例は、必須パラメータを含む URL を示しています。

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

お客様のニーズに応じて、パラメータを追加できます。次に例を示します。

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

URL のパラメータは、プロダクトが単一の Google Cloud プロジェクトにアクセスする必要があること、および顧客がコンソールに戻れることを示しています。

URL パラメータのリスト

サービスアカウント管理ページに送信できる URL パラメータのリストは次のとおりです。

パラメータ	説明
`service-name`	必須入力項目です。これは、パートナーエンジニアに提供したサービス名です。
`service-account-email`	必須入力項目です。これは、お客様用に作成したサービスアカウントのメールアドレスです。
`single`	true の場合、プロダクトが単一のプロジェクトにアクセスする必要があることを示します。
`hints=project-id-1`	サービスアカウントでアクセスするプロジェクトを設定します。プロジェクトはカンマで区切ります。
`filter=role1`	サービスアカウントに付与されているロールを、パートナーエンジニアに指定したロールのサブセットに制限します。フィルタを使用する場合は `roles/` を除外します。
`redirect`	お客様が管理コンソールに戻るためのリンクを提供します。このパラメータを使用するには、ドメイン名をパートナーエンジニアに登録する必要があります。

プロダクトをプレビューする