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

このページでは、アプリのフロントエンドを Google Cloud Marketplace と統合する手順について説明します。フロントエンドの統合により、顧客が Google Cloud Marketplace からアプリに切り替える際に円滑なエクスペリエンスを提供できます。

新規ユーザーのアカウント有効化ページを作成する

ユーザーが Google Cloud Marketplace からプロダクトを選択するとき、ユーザーはアプリで自分のアカウントを有効にする必要があります。システムでユーザーのアカウントを設定および承認するため、有効化ページを作成する必要があります。このページは、ユーザーがシステムのアカウントに登録する必要がある登録ページとして、またはアカウントを自動的に承認するページとして設定できます。有効化ページを設定する際には、ユーザーがユーザー名とパスワードを入力せずにページにアクセスできるようにしてください。

Google Cloud Marketplace では、ユーザーがリンクをクリックしてアプリに登録すると、有効化ページに HTTP POST リクエストが送信され、x-gcp-marketplace-token パラメータで JSON ウェブトークン（JWT）が送信されます。JWT には、ユーザーの調達アカウント ID が含まれており、Google Cloud Platform ユーザーとして識別されます。この ID を使用して、ユーザーの Google アカウントをシステムのアカウントにリンクする必要があります。

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

JWT を初めて使用する場合は、JWT の概要をご覧ください。

アカウント有効化ページのポータルへの追加

Producer Portal またはパートナーポータルを使用して、アカウント有効化ページの URL を追加できます。

Producer Portal

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

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

Producer Portal にアカウントの有効化ページを追加するには、次のようにします。

プロダクトのリストで貴社のプロダクト名をクリックします。
プロダクトの [概要] ページで [技術統合] セクションに移動し、[FRONTEND INTEGRATION] をクリックします。
[URL の登録] に、アカウント有効化ページの URL を入力します。

パートナーポータル

パートナーポータルの直接リンクは次のとおりです。

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

パートナーポータルにアカウントの有効化ページを追加するには、次のようにします。

ソリューションのリストで、作成したソリューション ID をクリックします。
[プランと機能] のページから、ページをクリックして編集します。
[URL の登録] に、アカウント有効化ページの URL を入力します。

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-pro.com など）。
roles は、ユーザーのロールを表す文字列の配列です。現時点では、** account_admin（ユーザーはプロダクトを購入した請求先アカウントの請求先アカウント管理者）か、** project_editor（ユーザーはその請求先アカウントに含まれるプロジェクトのプロジェクト編集者で、課金管理者ではない）のどちらかです。
user_identity は、ユーザーの難読化された GAIA ID です。これを使用して Open ID Connect を起動できます。

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 が返されます。

顧客のシングルサインオン（SSO）の統合

顧客がプロダクトに登録する際、最初にユーザー名とパスワードを入力しなくても、有効化ページでアカウントを登録できる必要があります。

SSO の統合では、JWT を使用してユーザーを認証します。JWT を初めて使用する場合は、JWT の概要をご覧ください。

SSO の統合は、Producer Portal またはパートナーポータルで設定できます。

Producer Portal

SSO の統合を設定するには:

プロダクトの [概要] ページで [技術統合] セクションに移動し、[FRONTEND INTEGRATION] をクリックします。
ダッシュボードにリンクするには、[ログイン URL] にダッシュボードの URL を入力します。
Google SSO を使用するには、[SSO ログインの有効化（省略可）] をクリックし、[SSO URL] 欄に SSO のログイン URL を入力します。
アプリのウェブインターフェースで、ユーザーが Google Cloud Marketplace からログインしたときにアプリに送信される JWT ペイロードを確認するコードを追加します。

認証用の JWT の形式は、ユーザーがアプリに初めて登録したときに送信される JWT と同じです。詳しくは、JWT を確認するをご覧ください。

パートナーポータル

SSO の統合を設定するには:

プロダクトの [プランと機能] ページに移動し、プロダクトのプランと機能の [EDIT] を選択します。
ダッシュボードにリンクするには、[Dashboard URL] にダッシュボードの URL を入力します。
Google SLO を使用するには、[SSO ログイン（省略可）] の [SSO の有効化] をクリックし、[SSO のログイン URL] 欄に SSO のログイン URL を入力します。[SSO API Keys URL] 欄に SSO API キーの URL を入力します。
アプリのウェブインターフェースで、ユーザーが Google Cloud Marketplace からログインしたときにアプリに送信される JWT ペイロードを確認するコードを追加します。

認証用の JWT の形式は、ユーザーがアプリに初めて登録したときに送信される JWT と同じです。詳しくは、JWT を確認するをご覧ください。

お客様のサービスアカウントのプロビジョニング

アプリでサービスアカウントが必要な場合は、パートナーエンジニアと協力してお客様にサービスアカウントをプロビジョニングし、お客様が必要な Identity and Access Management（IAM）のロールをサービスアカウントに付与するページを設定できます。ページへのリンクを、通常はアプリの管理コンソールから指定する必要があります。

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

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

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

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

コンソールへの URL の統合

ページの準備が整ったことをパートナーエンジニアから通知されたら、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`	お客様が管理コンソールに戻るためのリンクを提供します。このパラメータを使用するには、ドメイン名をパートナーエンジニアに登録する必要があります。

アプリのバックエンドの統合

SaaS プロダクトのテスト

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

新規ユーザーのアカウント有効化ページを作成する

アカウント有効化ページのポータルへの追加

Producer Portal

パートナー ポータル

JWT を確認する

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

顧客のシングル サインオン（SSO）の統合

Producer Portal

パートナー ポータル

お客様のサービス アカウントのプロビジョニング

コンソールへの URL の統合

URL パラメータのリスト

パートナーポータル

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

顧客のシングルサインオン（SSO）の統合

パートナーポータル

お客様のサービスアカウントのプロビジョニング