모바일 애플리케이션용 Google Cloud Armor와 통합

이 문서에서는 모바일 애플리케이션에서 reCAPTCHA Enterprise의 WAF 기능을 Google Cloud Armor와 통합하는 방법을 보여줍니다.

통합을 완료하려면 WAF용 reCAPTCHA Enterprise 기능을 하나 이상 구현하고 Google Cloud Armor 보안 정책을 구성해야 합니다. 그러나 모바일 애플리케이션에서 Google Cloud Armor와 통합을 위한 reCAPTCHA 작업 토큰만 구현할 수 있습니다.

시작하기 전에

1. reCAPTCHA Enterprise API를 사용 설정합니다.

   Enable the API

2. 보호하려는 작업을 식별합니다.

reCAPTCHA 작업 토큰 구현

작업 토큰을 생성하려면 모바일 애플리케이션에서 reCAPTCHA Enterprise를 실행해야 합니다. reCAPTCHA Enterprise에서 작업 토큰을 생성한 후에는 checkout과 같은 사용자 작업을 보호해야 하는 사전 정의된 요청 헤더에 작업 토큰을 연결합니다. 기본적으로 작업 토큰은 30분 동안 유효하지만 트래픽에 따라 달라질 수 있습니다. Google Cloud Armor가 토큰 속성을 평가할 수 있도록 토큰이 만료되기 전에 사전 정의된 요청 헤더에 작업 토큰을 연결해야 합니다.

reCAPTCHA 작업 토큰을 구현하려면 다음 안내를 따르세요.

1. 모바일 애플리케이션용 작업 토큰 키를 만듭니다.

   콘솔

   1. Google Cloud 콘솔에서 reCAPTCHA Enterprise 페이지로 이동합니다.

      reCAPTCHA Enterprise로 이동

   2. 페이지 상단의 리소스 선택기에 프로젝트 이름이 표시되는지 확인합니다.

      프로젝트 이름이 표시되지 않으면 리소스 선택기를 클릭한 다음 프로젝트를 선택합니다.

   3. 키 만들기를 클릭합니다.

      
   4. 표시 이름 필드에 키의 표시 이름을 입력합니다.
   5. WAF용 reCAPTCHA 키를 만들려는 애플리케이션 유형에 따라 적절한 작업을 수행합니다.
   참고: 모바일 애플리케이션에서 WAF용 reCAPTCHA 키 만들기는 Google Cloud Armor와 통합에만 지원됩니다. 이 통합을 위해 모바일 애플리케이션용 작업 토큰 키만 만들 수 있습니다.

   iOS 애플리케이션을 위한 WAF용 reCAPTCHA 키 만들기

   iOS 애플리케이션당 하나의 reCAPTCHA 키를 만드는 것이 좋습니다.

   1. 플랫폼 유형 선택 메뉴에서 iOS 앱을 선택합니다.
      
   1. iOS 번들 ID 목록 섹션에서 iOS 번들 ID 추가를 클릭합니다.

   2. 번들 ID 필드에 iOS 번들 ID 이름을 입력합니다.

   3. 선택사항: 번들 ID를 더 추가하려면 iOS 번들 ID 추가를 클릭하고 번들 ID 필드에 iOS 번들 ID 이름을 입력합니다.

   4. 선택사항: Apple 개발자 설정을 제공합니다.

      reCAPTCHA Enterprise가 트래픽에 대해 보다 정확한 위험 점수를 제공할 수 있으므로 이 데이터를 제공하는 것이 좋습니다.

      다음 정보를 입력합니다.

      • 비공개 키(.p8): Apple Developer Center의 인증서, 식별자, 프로필 아래에 생성됩니다.
      • 키 식별자: Apple 개발자 키 식별자(10자 문자열)입니다.
      • 팀 ID: 애플리케이션을 빌드하는 데 사용되는 프로비저닝 프로필을 소유하는 Apple팀 ID(10자 문자열)입니다.
   5. 번들 ID 확인 및 키 유형을 펼칩니다.
      1. WAF용 reCAPTCHA 키를 만들려면 다음을 수행합니다
         1. 웹 애플리케이션 방화벽(WAF) 전환을 사용 설정합니다.
         2. 서비스 메뉴에서 Cloud Armor를 선택합니다.
         3. 기능 메뉴에서 작업 토큰을 선택합니다.
      2. 번들 ID용 reCAPTCHA 키를 보호하려면 번들 ID 확인 사용 중지 전환 버튼이 중지되어 있는지 확인합니다.

      3. 비프로덕션 환경의 경우 평가가 생성될 때 키가 반환할 점수를 지정하려면 다음을 수행하세요.

         1. 테스트 키입니다 전환 버튼을 클릭합니다.
         2. 점수 상자에 0에서 1.0 사이의 점수를 지정합니다.
   6. 키 만들기를 클릭합니다.

   reCAPTCHA 키 페이지에 새로 생성된 키가 나열됩니다.

   Android 애플리케이션을 위한 WAF용 reCAPTCHA 키 만들기

   1. 플랫폼 유형 선택 메뉴에서 Android 앱을 선택합니다.
      
   2. Android 패키지 목록 섹션에서 Android 패키지 추가를 클릭합니다.

   3. Android 패키지 필드에 Android 패키지의 이름을 입력합니다.

      
   4. 선택사항: 패키지를 추가하려면 Android 패키지 추가를 클릭하고 Android 패키지 필드에 다른 Android 패키지의 이름을 입력합니다.
   5. 패키지 이름 인증, 앱 배포, 테스트 키를 펼칩니다.
   1. WAF용 reCAPTCHA 키를 만들려면 다음을 수행합니다
      1. 웹 애플리케이션 방화벽(WAF) 전환을 사용 설정합니다.
      2. 서비스 메뉴에서 Cloud Armor를 선택합니다.
      3. 기능 메뉴에서 작업 토큰을 선택합니다.
   2. 앱 내에서만 reCAPTCHA 키를 사용하도록 하려면 패키지 이름 확인 사용 중지 전환 버튼을 끕니다.
   3. Google Play 스토어 외에 다른 앱 스토어에서 사용할 수 있는 애플리케이션의 키를 만들려면 Google Play 스토어 외부에 배포된 애플리케이션 지원을 사용 설정합니다.

   4. 비프로덕션 환경의 경우 평가가 생성될 때 키가 반환할 점수를 지정하려면 다음을 수행하세요.

      1. 테스트 키입니다 전환 버튼을 클릭합니다.
      2. 점수 상자에 0에서 1.0 사이의 점수를 지정합니다.
   6. 키 만들기를 클릭합니다.

   reCAPTCHA 키 페이지에 새로 생성된 키가 나열됩니다.

   gcloud(iOS)

   reCAPTCHA 키를 만들려면 gcloud recaptcha keys create 명령어를 사용합니다.

   참고: 모바일 애플리케이션에서 WAF용 reCAPTCHA 키 만들기는 Google Cloud Armor와 통합에만 지원됩니다. 이 통합을 위해 모바일 애플리케이션용 작업 토큰 키만 만들 수 있습니다.

   아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

   • DISPLAY_NAME: 키 이름입니다. 일반적으로 사이트 이름입니다.
   • BUNDLE_IDs: 키를 사용할 수 있는 앱의 iOS 번들 ID입니다. 여러 번들 ID를 쉼표로 구분된 목록으로 지정합니다.
   • WAF_FEATURE: WAF 기능 이름입니다. action-token를 지정하세요.
   • WAF_SERVICE: WAF 서비스 제공업체의 이름입니다. Google Cloud Armor에 CA를 지정합니다.

   gcloud recaptcha keys create 명령어를 실행합니다.

   Linux, macOS 또는 Cloud Shell

   gcloud recaptcha keys create \
   --display-name=DISPLAY_NAME  \
   --ios --bundle-ids=BUNDLE_IDs \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE

   Windows(PowerShell)

   gcloud recaptcha keys create `
   --display-name=DISPLAY_NAME  `
   --ios --bundle-ids=BUNDLE_IDs `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE

   Windows(cmd.exe)

   gcloud recaptcha keys create ^
   --display-name=DISPLAY_NAME  ^
   --ios --bundle-ids=BUNDLE_IDs ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE

   응답에 새로 생성된 reCAPTCHA 키가 포함됩니다.

   gcloud(Android)

   reCAPTCHA 키를 만들려면 gcloud recaptcha keys create 명령어를 사용합니다.

   참고: 모바일 애플리케이션에서 WAF용 reCAPTCHA 키 만들기는 Google Cloud Armor와 통합에만 지원됩니다. 이 통합을 위해 모바일 애플리케이션용 작업 토큰 키만 만들 수 있습니다.

   아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

   • DISPLAY_NAME: 키 이름입니다. 일반적으로 사이트 이름입니다.
   • PACKAGE_NAMES: 키를 사용할 수 있는 앱의 Android 패키지 이름입니다. 여러 패키지 이름을 쉼표로 구분된 목록으로 지정합니다.
   • WAF_FEATURE: WAF 기능 이름입니다. action-token를 지정하세요.
   • WAF_SERVICE: WAF 서비스 제공업체의 이름입니다. Google Cloud Armor에 CA를 지정합니다.

   gcloud recaptcha keys create 명령어를 실행합니다.

   Linux, macOS 또는 Cloud Shell

   gcloud recaptcha keys create \
   --display-name=DISPLAY_NAME  \
   --android --package-names=PACKAGE_NAMES \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE

   Windows(PowerShell)

   gcloud recaptcha keys create `
   --display-name=DISPLAY_NAME  `
   --android --package-names=PACKAGE_NAMES `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE

   Windows(cmd.exe)

   gcloud recaptcha keys create ^
   --display-name=DISPLAY_NAME  ^
   --android --package-names=PACKAGE_NAMES ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE

   응답에 새로 생성된 reCAPTCHA 키가 포함됩니다.

   REST(iOS)

   참고: 모바일 애플리케이션에서 WAF용 reCAPTCHA 키 만들기는 Google Cloud Armor와 통합에만 지원됩니다. 이 통합을 위해 모바일 애플리케이션용 작업 토큰 키만 만들 수 있습니다.

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • DISPLAY_NAME: 키 이름입니다. 일반적으로 앱 이름입니다.
   • BUNDLE_IDs: 키를 사용할 수 있는 앱의 iOS 번들 ID입니다. 여러 번들 ID를 쉼표로 구분된 목록으로 지정합니다.
   • WAF_FEATURE: WAF 기능 이름입니다. action-token를 지정하세요.
   • WAF_SERVICE: WAF 서비스 제공업체의 이름입니다. Google Cloud Armor에 CA를 지정합니다.

   HTTP 메서드 및 URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

   JSON 요청 본문:

   {
     "displayName": "DISPLAY_NAME",
     "iosSettings": {
    "allowedBundleIds": "BUNDLE_IDS"
    },
      'wafSettings': "  {
          "wafService": "CA",
    "wafFeature": "ACTION_TOKEN"
     }
    }
   
   

   요청을 보내려면 다음 옵션 중 하나를 선택합니다.

   curl

   참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

   요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

   PowerShell

   참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

   요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   다음과 비슷한 JSON 응답이 표시됩니다.

   
   {
     "name": "projects/project-id/keys/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT",
     "displayName": "DISPLAY_NAME",
     "iosSettings": {
       "allowAllBundleIds": false,
       "allowedBundleIds": [
           BUNDLE_IDS
       ]
     },
     "labels": {},
     "wafSettings": {
         "wafService": "CA",
         "wafFeature": "ACTION_TOKEN"
     }
   }
   
   

   REST(Android)

   참고: 모바일 애플리케이션에서 WAF용 reCAPTCHA 키 만들기는 Google Cloud Armor와 통합에만 지원됩니다. 이 통합을 위해 모바일 애플리케이션용 작업 토큰 키만 만들 수 있습니다.

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • DISPLAY_NAME: 키 이름입니다. 일반적으로 앱 이름입니다.
   • PACKAGE_NAMES: 키를 사용할 수 있는 앱의 Android 패키지 이름입니다. 여러 패키지 이름을 쉼표로 구분된 목록으로 지정합니다.
   • WAF_FEATURE: WAF 기능 이름입니다. action-token를 지정하세요.
   • WAF_SERVICE: WAF 서비스 제공업체의 이름입니다. Google Cloud Armor에 CA를 지정합니다.

   HTTP 메서드 및 URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

   JSON 요청 본문:

   {
     "displayName": "DISPLAY_NAME",
     "androidSettings": {
     "allowedPackageNames":"PACKAGE_NAMES"
    },
      'wafSettings': "  {
          "wafService": "CA",
    "wafFeature": "ACTION_TOKEN"
     }
    }
   
   

   요청을 보내려면 다음 옵션 중 하나를 선택합니다.

   curl

   참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

   요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys"

   PowerShell

   참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

   요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   다음과 비슷한 JSON 응답이 표시됩니다.

   
   {
     "name": "projects/project-id/keys/6LcioSknAAAAABrjlMuZv2fjIGYMqwaAFC9izhoy",
     "displayName": "DISPLAY_NAME",
     "androidSettings": {
         "allowAllPackageNames": false,
         "allowedPackageNames": [
             PACKAGE_NAMES
         ],
         "supportNonGoogleAppStoreDistribution": false
     },
     "labels": {},
     "wafSettings": {
         "wafService": "CA",
         "wafFeature": "ACTION_TOKEN"
     }
   }
   
   

2. 생성된 작업 토큰 키와 모바일 애플리케이션의 reCAPTCHA Enterprise 모바일 SDK를 통합합니다. 자세한 내용은 모바일 애플리케이션 유형에 해당하는 문서를 참조하세요.

   • Android의 경우 WAF 키를 Android 애플리케이션과 통합을 참조하세요.
   • iOS의 경우 WAF 키를 iOS 애플리케이션과 통합을 참조하세요.

3. reCAPTCHA Enterprise에서 토큰을 받은 후 이 토큰을 사전 정의된 요청 헤더에 다음 형식으로 연결합니다.

   X-Recaptcha-Token: value-of-your-action-token
   

   다음 샘플 코드에서는 토큰을 연결하는 방법을 보여줍니다.

   Android

   자바 샘플 코드

   // This example shows how to send an HTTP request to the backend server
   // attached with the reCAPTCHA token in the header.
   //
   // @param serverUrl: the URL of the backend server.
   // @param rceToken: reCAPTCHA token that is attached to the header of the
   // HTTP request.
   
   public static void sendRequestToServerWithRceToken(
       String serverUrl, String rceToken) throws JSONException, IOException {
    URL url = new URL(String.format("http://%s/decryptcaptchacookie/accesswafserver", serverUrl));
    HttpURLConnection connection = (HttpURLConnection) url.openConnection();
    connection.setRequestProperty("X-Recaptcha-Token", rceToken);
   
    try {
       String requestBody = "['']";
       sendRequest(connection, requestBody, "AccessWithRceToken", "GET");
    } finally {
       connection.disconnect();
    }
   }
   
   private static void sendRequest(
       HttpURLConnection connection, String requestString, String requestName, String action)
       throws IOException {
    connection.setConnectTimeout(HTTP_CONNECT_TIMEOUT_MS);
    connection.setReadTimeout(HTTP_READ_TIMEOUT_MS);
    connection.setRequestProperty("Content-type", CONTENT_TYPE);
    connection.setRequestProperty(
       "Content-Length", Integer.toString(Utf8.encodedLength(requestString)));
    connection.setRequestMethod(action);
    connection.setDoOutput(true);
    connection.connect();
    try (OutputStream postStream = connection.getOutputStream()) {
       postStream.write(requestString.getBytes(UTF_8));
    }
   
    int responseCode = connection.getResponseCode();
    String response = connection.getResponseMessage();
    if (responseCode != HttpURLConnection.HTTP_OK) {
       throw new IOException(
          String.format(
             "Failed to complete request.\nResponse code:%s\nError Detail:\n%s",
             responseCode, response));
    }
   }

   iOS

   Swift 샘플 코드

   // This example shows how to send an HTTP request to the backend server
   // attached with the reCAPTCHA token in the header.
   // @param serverUrl: the URL of the backend server.
   // @param rceToken: reCAPTCHA token that is attached to the header of
   // the HTTP request.
   
    public static func accessWafServer(rceToken: String, serverUrl: String)
       async throws -> String
    {
       let requestURL = try HttpHelper.createRequestURL(endpoint: serverUrl)
       var request = try HttpHelper.createRequest(requestURL: requestURL, action: "GET")
       request.setValue(rceToken, forHTTPHeaderField: "X-Recaptcha-Token")
   
       let data = try await HttpHelper.getDataFromServer(request)
   
       return String(decoding: data, as: UTF8.self)
    }

Google Cloud Armor 보안 정책 구성

WAF용 reCAPTCHA Enterprise 기능을 구현한 후에는 봇 관리를 위해 reCAPTCHA Enterprise 토큰을 평가하는 Google Cloud Armor 보안 정책을 구성해야 합니다.

Google Cloud Armor 보안 정책을 구성하고 보안 정책에서 작업 토큰 키를 사용하는 방법은 봇 관리 규칙 구성을 참조하세요.

다음 단계

• 봇 관리 규칙 구성