앱의 프런트엔드 통합

이 페이지에서는 앱의 프런트엔드를 Cloud Marketplace와 통합하여 고객이 Cloud Marketplace에서 제품으로 원활하게 이동할 수 있도록 하는 방법을 설명합니다.

대략적으로 사용자 계정 생성을 처리하기 위한 가입 URL을 제공해야 합니다. 그러면 이 계정이 웹 콘솔에서 관리됩니다. 사용자가 로그인할 수 있는 URL도 제공해야 합니다. 필요한 경우 싱글 사인온(SSO)을 통합할 수 있습니다.

Producer Portal을 사용하여 앱의 프런트엔드 통합

한 곳에서 앱의 프런트엔드를 Google Cloud Marketplace와 통합하는 데 필요한 모든 정보에 액세스하려면 Producer Portal의 프런트엔드 통합 섹션을 사용하면 됩니다.

Producer Portal에 바로 연결되는 링크는 다음과 같습니다.

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

프런트엔드 통합 섹션에 액세스하려면 다음 안내를 따르세요.

제품 목록에서 제품 이름을 클릭합니다.
제품의 개요 페이지에서 기술 통합 섹션으로 이동하여 프런트엔드 통합을 클릭합니다.

가입 URL 추가

사용자가 Cloud Marketplace에서 제품을 구입하면 사용자를 위해 제품에 대한 계정을 만들어야 합니다. 이렇게 하려면 시스템에서 사용자 계정을 설정하고 승인하는 가입 페이지를 만들어야 합니다. 이 페이지를 사용자가 시스템의 계정에 가입하는 등록 페이지 또는 자동으로 계정을 승인하는 페이지로 설정할 수 있습니다.

가입 페이지를 만든 후 Producer Portal에 추가합니다.

제품 목록에서 제품 이름을 클릭합니다.
제품의 개요 페이지에서 기술 통합 섹션으로 이동하여 프런트엔드 통합을 클릭합니다.
가입 URL 필드에 가입 페이지 URL을 입력합니다.

사용자의 가입 정보 확인

시스템에서 아직 계정을 설정하지 않은 사용자는 Cloud Marketplace에서 YOUR_COMPANY_NAME으로 등록 버튼을 클릭해야 합니다. 고객이 버튼을 클릭하면 Google Cloud는 가입 페이지에 HTTP POST 요청을 전송하며, 여기서 x-gcp-marketplace-token 매개변수로 JSON 웹 토큰(JWT)을 전송합니다. JWT에는 사용자를 Google Cloud 사용자로 식별하는 사용자의 조달 계정 ID와 Google 계정 ID를 나타내는 난독화된 ID가 포함됩니다. 사용자의 Google 계정을 시스템 계정에 연결하려면 조달 계정 ID와 난독화된 ID를 모두 사용해야 합니다.

JWT를 확인한 후 백엔드 통합 단계에 설명된 대로 가입 페이지에서 Partner Procurement API에 계정 승인 요청을 보내야 합니다.

JWT 페이로드 및 확인 방법에 대한 자세한 내용은 아래의 JWT 확인을 참조하세요.

JWT를 처음 사용하는 경우 JWT 소개를 참조하세요.

로그인 URL 추가

앱의 로그인 페이지 URL을 지정해야 합니다.

Producer Portal에서 앱 로그인 페이지의 URL을 입력하려면 다음 안내를 따르세요.

제품 목록에서 제품 이름을 클릭합니다.
제품의 개요 페이지에서 기술 통합 섹션으로 이동하여 프런트엔드 통합을 클릭합니다.
로그인 URL 필드에 앱의 로그인 페이지 URL을 입력합니다.

(선택사항) 고객을 위한 싱글 사인온(SSO) 사용 설정

Producer Portal에서 SSO를 사용 설정하려면 다음 안내를 따르세요.

제품 목록에서 제품 이름을 클릭합니다.
1. 제품의 개요 페이지에서 기술 통합 섹션으로 이동하여 프런트엔드 통합을 클릭합니다.
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를 나타냅니다. 페이로드에서 iss 속성에 있는 JSON 객체로부터 키를 조회하려면 이 키 ID를 사용합니다.

페이로드

{
  "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입니다. 사용자의 Google 계정을 시스템 계정에 연결하려면 이 ID를 사용해야 합니다.
ississ는 JWT를 보낸 사람입니다. ississ 클레임의 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 OAuth 2.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에 추가해야 합니다.

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`	고객이 관리 콘솔로 돌아갈 수 있는 링크를 제공합니다. 이 매개변수를 사용하려면 도메인 이름을 파트너 엔지니어에게 등록해야 합니다.

제품 미리보기

앱의 프런트엔드 통합

Producer Portal을 사용하여 앱의 프런트엔드 통합

가입 URL 추가

사용자의 가입 정보 확인

로그인 URL 추가

(선택사항) 고객을 위한 싱글 사인온(SSO) 사용 설정

고객의 SSO 로그인 정보 확인

JWT 확인

JWT 페이로드

페이로드 확인

login_hint로 Google 로그인 시작

고객의 서비스 계정 만들기

서비스 계정 프로비저닝

서비스 계정 관리 페이지를 제품 콘솔에 통합

URL 매개변수 목록

`login_hint`로 Google 로그인 시작