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

このページでは、アプリのフロントエンドを 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

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

  1. プロダクトのリストで貴社のプロダクト名をクリックします。

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

登録用 URL を追加する

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

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

  1. プロダクトのリストで貴社のプロダクト名をクリックします。

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

  3. 登録ページの 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 を入力する手順は次のとおりです。

  1. プロダクトのリストで貴社のプロダクト名をクリックします。

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

  3. アプリのログインページの URL を [ログイン URL] フィールドに入力します。

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

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

  1. プロダクトのリストで貴社のプロダクト名をクリックします。

    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: ユーザーが、その請求先アカウントに含まれるプロジェクトの編集者（利用資格管理者）であり、課金管理者ではないことを示します。

  • 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 を受け取ったら、以下を確認する必要があります。

  1. JWT の署名が Google の公開鍵 を使用していることを確認します。

  2. exp クレームを確認して、JWT の有効期限が切れていないことを確認します。

  3. aud クレームがプロダクトの正しいドメインであることを確認します。

  4. iss クレームが https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com であることを確認します

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