AWS Marketplace 연동 가이드 | 01. AWS Marketplace Seller 계정 생성부터 x-amzn-marketplace-token 토큰 수신까지

AWS Marketplace 연동 가이드 | 01. AWS Marketplace Seller 계정 생성부터 x-amzn-marketplace-token 토큰 수신까지

AWS Marketplace 연동 가이드 | 02. AWS Marketplace Client 생성하기

AWS Marketplace 연동 가이드 | 03. ResolveCustomer

AWS Marketplace 연동 가이드 | 04. BatchMeterUsage

---

AWS Marketplace란

구글이나 애플의 앱 스토어에 앱을 등록하는 것처럼, AWS Marketplace에 서비스를 등록할 수 있습니다. 사용자 입장에서는 신용카드 등록, 청구서 발송 대신에 새로운 타입의 결제수단으로써 AWS Maketplace라는 선택지가 생기게 됩니다. AWS 예산을 받아서 사용하는 고객의 경우, 신규 서비스의 구독을 위해서 별도의 예산을 요청하는 과정을 생략하고 이미 할당받은 예산 안에서 서비스를 이용할 수 있습니다. 서비스를 등록하는 입장에서는 신규 고객을 유치할 수 있는 새로운 수단이 생깁니다.

Terminolgy

본 문서에서는 AWS Marketplace를 AWS MP라고 줄여서 부르겠습니다.

• AWS MP = AWS Marketplace

AWS Marketplace Seller Account 생성하기

AWS MP를 관리할 계정을 생성해야 합니다. Mangagement Portal에서 Seller로 등록하고 세금과 은행 정보를 입력해야 합니다.

https://docs.aws.amazon.com/marketplace/latest/userguide/saas-getting-started.html

💡 연동 일정을 넉넉하게 설정해야 합니다.

세금과 은행 정보를 담당부서에서 취합하는데 수 일이 걸릴 수 있습니다. 

💡어떤 AWS 계정을 AWS Marketplace Seller 계정으로 설정할지 고민해봐야합니다

신규 사용자 구독 과정에서 AWS Marketplace의 ResolveCustomer API를 호출해야합니다. 그런데 이 API는 AWS Marketplace Seller 계정에서 호출되어야 합니다. (The API needs to called from the seller account id used to publish the SaaS application to successfully resolve the token.) 만약 EC2를 관리하는 계정과 AWS Marketplace Seller 계정이 다르다면 이후에 설명할 AWS의 AssumeRole API를 사용해서 권한을 취득하는 로직을 추가해야합니다.

https://docs.aws.amazon.com/marketplacemetering/latest/APIReference/API_ResolveCustomer.html

 

과금 방식 결정하기

AWS MP에 판매할 상품의 종류에 따라서 과금 방식이 달라질 수 있습니다. AWS MP에서는 다양한 과금 방식을 지원합니다. 참고로 AWS MP에서는 원화로는 결제가 불가능합니다. 달러로만 과금됩니다. 그리고 무료 서비스는 등록할 수 없습니다.

https://docs.aws.amazon.com/marketplace/latest/userguide/pricing.html

 

AWS MP에 등록하려는 서비스의 성격에 맞는 과금 방식을 잘 선택해야합니다.

https://docs.aws.amazon.com/marketplace/latest/userguide/pricing.html#pricing-models

본 문서에서 사용자의 사용량에 따라서 과금을 하는 SaaS Subscriptions 과금 방식을 사용하겠습니다.

💡 과금 방식에 따라서 연동 방식이 달라집니다

과금 방식이 달라지면 사용해야하는 AWS Marketplace API가 달라집니다. 그래서 초기 단계에서 과금 방식을 확실히 결정해두어야 합니다. 과금 방식이 변경되면 개발을 다시해야하는 상황이 벌어집니다. 배포 일정이 최소 몇 주 지연될 수 있습니다.

💡과금 모델이 적합한지 미리 검토하는 방법

2024.01.16 - [개발/AWS Marketplace] - AWS Marketplace SaaS Subscription 과금 모델이 적합한지 미리 검토하는 방법

AWS MP에 상품 등록하기

AWS MP에 상품을 등록하기 전에 AWS MP 제품의 상태에 대해서 미리 알고 있어야 이후의 과정이 편해집니다.

💡AWS Marketplace SaaS 제품의 Lifecycle

2024.01.16 - [개발/AWS Marketplace] - AWS Marketplace SaaS 제품의 Lifecycle

 

AWS MP에 상품을 등록하는 과정은 가이드 문서에 잘 나와있습니다. 

https://docs.aws.amazon.com/marketplace/latest/userguide/saas-create-product-page.html

💡제품 등록 과정에서 개발자 또는 엔지니어의 도움이 필요할 수 있습니다.

예를 들어, 제품에 들어갈 Logo는 반드시 S3에 등록되어있는 경로를 제공해야합니다.

💡Fulfillment URL
고객이 AWS MP에 등록된 상품을 구독했을 때 Redirect되는 URL입니다. 로그인 페이지, 계정 생성 페이지 등 등록할 서비스를 사용하기 위한 첫 페이지의 경로를 지정합니다. 어떤 페이지를 첫 페이지로 지정할지, 첫 페이지에서 고객의 구독 정보는 어떤 식으로 저장할지 등은 모두 자유롭게 결정해야합니다.

💡 Allowlisted AWS accounts
제품을 처음 등록하면 Limited 상태로 저장됩니다. Limited 상태에서는 테스트 계정으로만 상품을 조회할 수 있습니다. Allowlisted AWS accounts는 Limited 상태의 제품을 조회할 수 있는 계정을 입력합니다. 제품 등록 담당자, 연동을 담당하는 개발자, PM 등의 AWS 계정의 ID를 입력합니다.

💡대부분의 정보는 한 번 입력한 뒤에 수정이 불가능합니다.
상품의 설명 정보, 과금 단위, 과금 단위 별 과금액 등 대부분의 정보는 변경이 불가능합니다. 내용의 수정이 필요하면 제품을 새로 등록해야합니다.

신규 구독 처리하기 (AWS Marketplace Token 수신하기)

사용자 관점

처음 생성한 AWS MP 제품은 LIMITED 상태라서 Allowlisted AWS accounts에 추가된 계정으로만 테스트 상품을 조회할 수 있습니다. 상품을 조회하면 사진 하단의 Subscribe를 눌러 구독을 합니다. 그러면 Set up your account 버튼이 나타납니다. 이 버튼을 눌렀을 때 Redirect되는 경로가 Fulfillment URL 입니다.

Fullfillment URL로 redirect된 이후의 연동은 전적으로 연동하는 서비스에 달려있습니다. 로그인 페이지로 redirect해서 이미 존재하는 계정으로 로그인하고, 그 계정의 결제 수단을 AWS MP로 변경할 수 있습니다. 또는 AWS MP를 구독할 때마다 매번 새로운 계정을 생성해야한다는 정책을 적용할 수도 있습니다.

AWS Marketplace를 지원하는 다른 서비스들을 좀 살펴봤었습니다. 일부 서비스에서는 항상 기존 계정으로 로그인하도록 유도한 뒤, 해당 계정이 결제 수단이 없으면 AWS MP를 연동해주었습니다. 만약 그 계정에 이미 결제 수단이 등록되어 있는 경우에는 연동 실패 메시지를 띄우고, 기존 결제 수단으로 계산된 과금액을 모두 지불한 뒤에 다시 시도하라는 메시지를 띄우기도 했습니다.

본 가이드에서는 최대한 간단하게 AWS MP 연동을 시도할 때마다 매번 새로운 계정을 생성하는 방향으로 연동을 진행하기 위해 계정 생성 페이지로 Redirect 시켰습니다.

계정 생성 폼을 입력하고 가입 버튼을 누를 때 aws_marketplace_token이 함께 전달됩니다.

 

개발자 관점

Redirect될 때 Fulfillment URL로 지정한 경로로 POST 요청이 x-amzn-marketplace-token 토큰을 가진 상태로 전달됩니다.

aws marketplace token 토큰을 수신하는 내용은 아래의 가이드에 나와있습니다.

아래는 aws marketplace token을 전달받아서 회원가입 페이지로 다시 Redirect하도록 구현한 예시입니다.

@PostMapping(value = "/account/create/aws/marketplace")
public String accountRegistrationAwsMarketplace(@RequestParam(value = "x-amzn-marketplace-token", required = true) String awsMarketplaceToken,
                                                Model model, HttpServletRequest request, HttpServletResponse response){
    model.addAttribute("aws_marketplace_token", awsMarketplaceToken);
    return "/account/v3-create";
}

Redirect된 회원가입 페이지(”account/v3-create”)에서는 aws_marketplace_token을 포함하고 있습니다. 회원 가입을 시도할 때 aws marketplace token이 함께 전달되도록 설정했습니다.

💡aws marketplace token에는 ‘+’ 문자가 포함될 수 있습니다.

‘+’ 문자는 queryString으로 전달될 때 ‘ ‘(빈 문자열)로 치환될 수 있습니다. 이렇게 변경된 토큰을 사용하면 이후의 단계에서 ResolveCustomer API를 호출할 때 Registration token is invalid가 발생합니다. 이를 막기 위해서는 아래와 같이 치환해주는 로직을 추가하면 됩니다.

@PostMapping(value = "/account/create/aws/marketplace")
public String accountRegistrationAwsMarketplace(@RequestParam(value = "x-amzn-marketplace-token", required = true) String awsMarketplaceToken,
                                                Model model, HttpServletRequest request, HttpServletResponse response){
		// 토큰에 포함된 + 문자가 공백으로 대체 되는 것을 복원
		awsMarketplaceToken = awsMarketplaceToken.replaceAll(" ", "+");
    model.addAttribute("aws_marketplace_token", awsMarketplaceToken);
    return "/account/v3-create";
}​

💡aws marketplace token이 유실되지 않도록 주의해야합니다.

회원 가입 과정에서 비밀번호 불일치 등의 이유로 페이지 reload가 발생할 수 있습니다. Fullfillment URL의 동작 방식을 어떻게 정의하느냐에 따라서 token이 저장되는 시점이 달라질 수 있습니다. 저장되기 전에 에러가 발생해서 token이 유실된다면, 사용자가 다시 AWS MP 포탈로 가서 구독 버튼을 눌러야하는 불편함이 발생할 수 있습니다.

💡신규 계정을 생성하도록 유도한다면

일반 회원 가입 페이지와 AWS MP 연동을 시도하는 계정의 계정 생성 로직을 통합해서 작성할 때에는 토큰의 값을 required=false로 지정해야 합니다. 기존 계정 생성 로직과 분리할지 통합할지는 상황에 따라서 달라지니 잘 판단해야 합니다.

@PostMapping(value = "/account/create", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public String accountCreate(@Valid @ModelAttribute AccountCreateForm form, BindingResult result,
                            @RequestParam(value = "x-amzn-marketplace-token", required = false, defaultValue = "") String awsMarketplaceToken) throws IOException {
    if (conf.enable_aws_marketplace) {
        // 비밀번호 불일치 등 오류가 발생했을 때에도 token 정보가 유지되도록 항상 추가
        model.addAttribute("aws_marketplace_token", awsMarketplaceToken);
    }
		... 회원가입 처리 ...
}​

 

💡 CORS 문제가 발생할 수 있습니다

aws marketplace의 연동 과정에서 whatap 계정 생성을 위해서 aws marketplace console → service.whatap.io 계정 생성 페이지로 redirect되는 동선을 사용했습니다. 이 과정에서 CORS 문제가 발생할 수 있습니다. CORS 필터에서 허용된 도메인으로 "aws.amazon.com"을 추가하면 됩니다.