PC용 Play Integrity API를 사용하면 상호작용과 서버 요청이 정품 PC 기기에서 비롯되는지 확인할 수 있습니다. 위험하고 허위일 가능성이 있는 상호작용을 감지함으로써 앱의 백엔드 서버는 공격을 방지하고 악용을 줄이기 위한 적절한 조치를 취할 수 있습니다.
API는 다음과 같은 잠재적 위협을 감지하는 데 도움이 되는 확인 결과를 반환합니다.
- 위험한 기기 및 환경:
deviceIntegrity확인 결과를 사용하면 앱이 정품 PC 기기 또는 정품 PC용 Google Play 게임즈 인스턴스에서 실행되는지 확인할 수 있습니다.
API와 통합
PC용 Play Integrity API를 앱에 통합하려면 먼저 Google Cloud 콘솔에서 초기 설정을 해야 합니다. 그런 다음 각 무결성 검사에 대해 다음 단계를 따라야 합니다.
- 무결성 토큰 준비
- 무결성 토큰 요청
- 토큰 데이터 요청
Google Cloud 콘솔에서 초기 설정
Play Integrity API를 호출하는 모든 앱 또는 SDK는 Google Cloud 프로젝트를 사용하여 호출을 인증하고 API 사용량을 모니터링해야 합니다. 새 Cloud 프로젝트를 만들거나 앱이 Google Play 외부에 독점적으로 배포되는 경우 Google Cloud 콘솔에서 Play Integrity API 응답을 사용 설정할 수 있습니다.
Google Cloud 콘솔에서 새 Cloud 프로젝트를 만들거나 PC용 Play Integrity API와 함께 사용할 기존 Cloud 프로젝트를 선택합니다. API 및 서비스로 이동합니다. API 및 서비스 사용 설정을 선택합니다. Play Integrity API를 검색한 후 사용 설정합니다. 이제 Play Integrity API를 앱에 통합할 수 있습니다.
1단계: 무결성 토큰 준비하기
void PrepareIntegrityToken( const PrepareIntegrityTokenParams & params, PrepareIntegrityTokenContinuation continuation )
무결성 토큰을 요청하기 전에(RequestIntegrityToken 참고) Play Integrity API를 준비해야 합니다. 이렇게 하면 무결성 확인 결과 요청을 할 때 중요한 경로의 지연 시간을 줄이기 위해 Google Play에서 기기의 부분 증명 정보를 스마트하게 캐시할 수 있습니다.
성공하면 무결성 토큰을 요청하는 데 사용해야 하는 RequestTokenData가 포함된 PrepareIntegrityTokenResultValue로 연속이 호출됩니다. 이 데이터는 메모리에 캐시되어 RequestIntegrityToken 호출을 위해 애플리케이션 세션 기간 동안 재사용되어야 합니다. 애플리케이션에서 무결성 확인 결과를 완전히 재평가해야 한다고 판단하는 경우에만 PrepareIntegrityToken을 호출해야 합니다.
| 세부정보 | |
|---|---|
| 매개변수 | params: Google Cloud 프로젝트 번호가 포함된 매개변수입니다. continuation: 무결성 토큰 제공자를 반환하는 비동기 콜백입니다. |
2단계: 무결성 토큰 요청
void RequestIntegrityToken( const RequestIntegrityTokenParams & params, RequestIntegrityTokenContinuation continuation )
무결성 토큰은 애플리케이션이 기기가 무단 변경되지 않았음을 확인할 수 있는 메커니즘입니다. 예를 들어 백엔드 서버는 무결성 토큰을 사용하여 다음을 확인할 수 있습니다.
- 정품 기기: 애플리케이션이 PC용 Google Play 게임즈의 정품 인스턴스가 포함되어 있고 조작되지 않은 정품 기기에서 실행되는지 확인합니다.
PC용 Play Integrity API로 앱에서 사용자 작업을 확인할 때 RequestIntegrityTokenParams::request_hash 필드를 사용하여 조작 공격을 완화할 수 있습니다. 예를 들어 게임에서 플레이어의 점수를 게임의 백엔드 서버에 보고하려고 할 때 서버는 프록시 서버에서 이 점수가 조작되지 않았는지 확인하려고 합니다. Play Integrity API는 서명된 무결성 응답 내에서 이 필드에 설정한 값을 반환합니다. requestHash가 없으면 무결성 토큰은 기기에만 바인딩되고 특정 요청에는 바인딩되지 않으므로 공격이 발생할 수 있습니다.
무결성 확인 결과를 요청할 때 이 문제를 완화하려면 다음을 따르세요.
- 발생하는 사용자 작업 또는 서버 요청에서 모든 관련 요청 매개변수(예: 안정적인 요청 직렬화의 SHA256)의 다이제스트를 계산합니다.
- RequestIntegrityTokenParams::request_hash 필드를 다이제스트로 설정합니다.
| 세부정보 | |
|---|---|
| 매개변수 | params: 준비된 RequestTokenData 및 무결성 확인 요청 해시가 포함된 매개변수입니다. continuation: 데이터를 반환하는 비동기 콜백입니다. |
3단계: 토큰 데이터 요청
무결성 확인 결과를 요청하면 Play Integrity API가 암호화된 응답 토큰을 제공합니다. 기기 무결성 확인 결과를 가져오려면 Google 서버에서 무결성 토큰을 복호화해야 합니다. 이렇게 하려면 다음 단계를 완료하세요.
- 앱에 연결된 Google Cloud 프로젝트 내에서 서비스 계정을 만듭니다.
앱 서버에서 playintegrity 범위를 사용하여 서비스 계정 사용자 인증 정보로부터 액세스 토큰을 가져오고 다음과 같이 요청합니다.
playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \ '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'JSON 응답을 읽습니다.
결과 페이로드는 개발자가 제공한 정보와 함께 무결성 확인 결과 및 세부정보가 포함된 일반 텍스트 토큰입니다. 토큰 형식은 다음과 같습니다.
{
"requestDetails": { ... },
"deviceIntegrity": { ... },
}
각 무결성 확인 결과를 확인하기 전에 먼저 requestDetails 필드의 값이 원래 요청의 값과 일치하는지 확인해야 합니다. 다음 섹션에서는 각 필드를 자세히 설명합니다.
요청 세부정보 필드
requestDetails 필드는 요청에 관한 정보를 포함합니다. 표준 요청의 경우 requestHash에, 기존 요청의 경우 nonce에 개발자가 제공한 정보가 포함됩니다.
"requestDetails": {
// Application package name this attestation was requested for.
// Note that this field might be spoofed in the middle of the request.
"requestPackageName": "com.package.name",
// The timestamp when the integrity token was requested.
"requestTime": "1675655009345"
// Request hash provided by the developer.
"requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}
이러한 값은 원래 요청의 값과 일치해야 합니다. 따라서 requestPackageName과 requestHash가 원래 요청에서 전송된 것과 일치하는지 확인하여 JSON 페이로드의 requestDetails 부분을 확인합니다.
기기 무결성 필드
deviceIntegrity 필드에는 deviceRecognitionVerdict 값 하나만 포함되며, 여기에는 기기가 앱 무결성을 얼마나 잘 시행할 수 있는지 나타내는 라벨이 하나 이상 포함됩니다. 기기가 라벨 기준을 충족하지 않으면 deviceIntegrity 필드에서 deviceRecognitionVerdict이 생략됩니다.
"deviceIntegrity": {
"deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
기본적으로 deviceRecognitionVerdict에는 다음이 포함될 수 있습니다.
MEETS_PC_INTEGRITY- 앱이 정품 PC 환경에서 실행되고 기기 내 조작이 감지되지 않은 경우 확인 결과를 반환합니다.
- 비어 있음(빈 값)
- 앱이 공격(예: API 후킹)이나 시스템 손상(예: 루팅됨) 징후가 있는 기기에서 실행되거나, 앱이 Google Play 무결성 검사를 통과하지 못한 에뮬레이터와 같은 실제 기기에서 실행되지 않습니다.
사용 제한
Play Integrity API 사용량 한도
앱의 일일 최대 요청 수는 총 10,000개입니다. 앱에서 증가된 사용자 수를 처리해야 하는 경우 다음 안내에 따라 이 일일 최대한도의 상향을 요청할 수 있습니다.
| 작업 | 앱별 일일 할당량 | 참고 |
|---|---|---|
| 토큰 요청 | 10,000명 | 기존 및 표준 요청을 위한 Play Integrity API와 PC용 Play Integrity API 간에 공유됩니다. |
| Google 서버에서의 토큰 복호화 | 10,000명 | 기존 및 표준 요청을 위한 Play Integrity API뿐만 아니라 PC용 Play Integrity API 간에 공유됩니다. |
일일 최대 요청 수 늘리기
일일 최대 요청 수를 늘릴 수 있으려면 Google Play 외에 다른 배포 채널에서도 앱을 사용할 수 있어야 합니다.
일일 최대 요청 수 증가를 요청하려면 다음을 실행하세요.
- Play Console에서 Play Integrity API에 사용 중인 Google Cloud 프로젝트를 연결합니다.
- 권장되는 재시도 전략을 포함하여 API 로직을 올바르게 구현하고 있는지 확인합니다.
- 이 양식을 사용하여 할당량 상향 조정을 요청합니다.
Play Integrity API 할당량을 늘리는 데는 최대 일주일이 걸릴 수 있으므로 서비스가 중단되지 않도록 할당량 알림을 설정할 수도 있는 Google Play Console 또는 Google Cloud 콘솔에서 Play Integrity API 사용을 모니터링하는 것이 좋습니다.
할당량 증가는 무결성 토큰을 생성하는 클라이언트 호출과 무결성 토큰을 복호화하고 확인하는 서버 호출에 모두 자동으로 적용됩니다.
보안 고려사항
다음 권장사항을 따르면 Play Integrity API가 앱에 최대한의 가치를 제공합니다.
악용 방지 전략 수립
Play Integrity API는 단독 악용 방지 메커니즘이 아니라 전반적인 악용 방지 전략의 일부로 다른 신호와 함께 사용할 때 가장 좋습니다. 이 API를 앱의 다른 적절한 보안 권장사항과 함께 사용하세요. 기본적으로 앱은 모든 설치에서 하루에 총 10,000회까지 요청을 할 수 있습니다. 일일 최대한도 증가를 요청할 수 있습니다.
작업 진행 전 원격 분석 수집 및 잠재고객 파악
Play Integrity API 확인 결과에 따라 앱의 동작을 변경하기 전에 시행 없이 API를 구현하여 기존 잠재고객의 현재 상황을 파악할 수 있습니다. 현재 설치한 사용자 수에서 반환되는 확인 결과를 파악하고 나면 계획 중인 모든 시행의 영향을 추정하고 그에 따라 악용 방지 전략을 조정할 수 있습니다.
적절한 시점에 무결성 확인 결과 요청
방어하려는 작업 또는 서버 요청 시점에 최대한 가깝게 API 요청을 해야 합니다.
API 요청을 복제하기 어렵게 하기
API 요청에는 조작 및 유사한 공격을 방지하는 데 사용되는 requestHash 필드가 있습니다. 이 필드에는 앱 요청의 모든 관련 값 다이제스트를 포함해야 합니다. 콘텐츠 결합 사용 방법의 안내에 따라 앱의 표준 요청을 보호하세요.
무결성 확인 결과 캐싱 방지
무결성 확인 결과를 캐시하면 악의적인 행위자가 좋은 기기의 확인 결과를 다른 환경에서 악의적인 목적으로 재사용하는 공격인 프록시화의 위험이 증가합니다.
서버에서 앱으로 다양한 응답 전송
결정 결과의 범위가 있는 것이 각 응답마다 서버에서 다시 앱으로 바이너리 허용 / 거부 응답을 전송하는 것보다 복제하기가 더 어렵습니다. 예를 들어 허용, 허용(제한 있음), CAPTCHA 완료 후 허용(제한 있음), 거부와 같은 일련의 관련 응답을 사용할 수 있습니다.
실행 가능한 오류 메시지 표시
가능한 경우 사용자에게 유용한 오류 메시지를 제공하여 문제 해결을 위해 할 수 있는 작업을 사용자가 알도록 합니다.
예기치 않은 문제 또는 서비스 중단에 대한 계획 수립
Play 상태 대시보드에는 Play Integrity API의 서비스 상태에 관한 정보와 장애 및 서비스 중단에 관한 정보가 표시됩니다. 예상치 못한 대규모 Play Integrity API 서비스 중단이 발생하는 경우 백엔드 서버가 작동하는 방식을 미리 계획해야 합니다.
서비스 약관 및 데이터 보안
PC용 Play Integrity API에 액세스하거나 이를 사용하면 Play Integrity API 서비스 약관에 동의하는 것으로 간주됩니다. API에 액세스하기 전에 모든 관련 약관 및 정책을 자세히 읽고 숙지하세요.
Google Play에는 개발자가 앱의 데이터 수집, 공유 및 보안 관행을 공개하여 사용자에게 정보를 제공할 수 있는 데이터 보안 섹션이 있습니다. 데이터 양식을 작성하는 데 도움이 되는 정보는 Play Integrity API가 데이터를 처리하는 방법을 참고하세요.