앱 체크 웹 Codelab

1. 소개

최종 업데이트: 2023년 2월 23일

Firebase 리소스에 대한 무단 액세스를 방지하려면 어떻게 해야 하나요?

Firebase 앱 체크를 사용하여 수신 요청에 실제 앱에서 발생한 요청임을 증명하는 증명이 첨부되어야 하고 적절한 증명이 없는 트래픽은 차단되어야 한다고 요구함으로써 승인되지 않은 클라이언트가 백엔드 리소스에 액세스하는 것을 방지할 수 있습니다. Firebase 앱 체크는 플랫폼별 증명 제공업체를 사용하여 클라이언트의 진위를 확인합니다. 웹 앱의 경우 앱 체크는 reCAPTCHA v3 및 reCAPTCHA Enterprise를 증명 제공업체로 지원합니다.

앱 체크는 Cloud Firestore, 실시간 데이터베이스, Cloud Functions, Identity Platform을 사용한 Firebase 인증, 직접 호스팅하는 백엔드에 대한 요청을 보호하는 데 사용할 수 있습니다.

빌드할 항목

이 Codelab에서는 먼저 앱 체크를 추가한 다음 적용하여 채팅 애플리케이션을 보호합니다.

개발자가 직접 빌드하는 초보자 친화적인 채팅 앱입니다.

학습 내용

  • 백엔드의 무단 액세스를 모니터링하는 방법
  • Firestore 및 Cloud Storage에 시정 조치를 추가하는 방법
  • 로컬 개발을 위해 디버그 토큰으로 애플리케이션을 실행하는 방법

필요한 사항

  • 원하는 IDE/텍스트 편집기
  • 일반적으로 Node.js와 함께 제공되는 패키지 관리자 npm
  • 계정과 호환되도록 설치 및 구성된 Firebase CLI
  • 터미널/콘솔
  • 원하는 브라우저(예: Chrome)
  • Codelab의 샘플 코드 (코드 가져오기 방법은 Codelab의 다음 단계를 참고하세요.)

2. 샘플 코드 가져오기

명령줄에서 Codelab의 GitHub 저장소를 클론합니다.

git clone https://github.com/firebase/codelab-friendlychat-web

또는 Git이 설치되어 있지 않으면 저장소를 ZIP 파일로 다운로드할 수 있습니다.

시작 앱 가져오기

IDE를 사용하여 클론된 저장소에서 📁 appcheck-start 디렉터리를 열거나 가져옵니다. 이 📁 appcheck-start 디렉터리에는 모든 기능을 갖춘 채팅 웹 앱이 될 Codelab의 시작 코드가 포함되어 있습니다. 📁 appcheck 디렉터리에는 Codelab의 완성된 코드가 있습니다.

3. Firebase 프로젝트 만들기 및 설정

Firebase 프로젝트 만들기

  1. Firebase에 로그인합니다.
  2. Firebase Console에서 프로젝트 추가를 클릭한 후 Firebase 프로젝트의 이름을 FriendlyChat으로 지정합니다. Firebase 프로젝트의 프로젝트 ID를 기억합니다.
  3. '이 프로젝트에 Google 애널리틱스 사용 설정'을 선택 해제합니다.
  4. '프로젝트 만들기'를 클릭합니다.

빌드할 애플리케이션은 웹 앱에 사용할 수 있는 Firebase 제품을 사용합니다.

  • Firebase 인증 - 사용자가 앱에 간편하게 로그인할 수 있음
  • Cloud Firestore - 클라우드에 구조화된 데이터를 저장하고 데이터가 변경되면 인스턴트 알림을 받을 수 있음
  • Firebase용 Cloud Storage: 클라우드에 파일을 저장합니다.
  • Firebase 호스팅 - 애셋을 호스팅하고 제공할 수 있음
  • Firebase 클라우드 메시징: 푸시 알림을 전송하고 브라우저 팝업 알림을 표시합니다.
  • Firebase Performance Monitoring: 앱의 사용자 성능 데이터를 수집합니다.

이러한 제품 중에는 특수 구성이 필요하거나 Firebase Console을 사용하여 사용 설정해야 하는 제품이 있습니다.

Firebase 요금제 업그레이드

Firebase용 Cloud Storage를 사용하려면 Firebase 프로젝트가 사용한 만큼만 지불 (Blaze) 요금제를 사용해야 합니다. 즉, Cloud Billing 계정에 연결되어 있어야 합니다.

  • Cloud Billing 계정에는 신용카드와 같은 결제 수단이 필요합니다.
  • Firebase와 Google Cloud를 처음 사용하는 경우 $300 크레딧과 무료 체험판 Cloud Billing 계정을 받을 자격이 되는지 확인하세요.
  • 이벤트의 일환으로 이 Codelab을 진행하는 경우 주최자에게 사용 가능한 Cloud 크레딧이 있는지 문의하세요.

프로젝트를 Blaze 요금제로 업그레이드하려면 다음 단계를 따르세요.

  1. Firebase Console에서 요금제를 업그레이드하도록 선택합니다.
  2. Blaze 요금제를 선택합니다. 화면에 표시된 안내에 따라 Cloud Billing 계정을 프로젝트에 연결합니다.
    이 업그레이드의 일환으로 Cloud Billing 계정을 만들어야 하는 경우 업그레이드를 완료하기 위해 Firebase Console의 업그레이드 흐름으로 돌아가야 할 수 있습니다.

프로젝트에 Firebase 웹 앱 추가

  1. 웹 아이콘 58d6543a156e56f9.png을 클릭하여 새 Firebase 웹 앱을 만듭니다.
  2. 앱을 Friendly Chat이라는 닉네임으로 등록한 다음 이 앱의 Firebase 호스팅도 설정합니다 옆의 체크박스를 선택합니다. 앱 등록을 클릭합니다.
  3. 다음 단계에서는 npm과 구성 객체를 사용하여 Firebase를 설치하는 명령어가 표시됩니다. 이 객체는 Codelab의 뒷부분에서 복사하므로 지금은 다음을 누릅니다.

웹 앱에 Firebase 추가 창

  1. 그러면 Firebase CLI를 설치하는 옵션이 표시됩니다. 아직 설치하지 않았다면 npm install -g firebase-tools 명령어를 사용하여 지금 설치합니다. 다음을 클릭합니다.
  2. 그러면 Firebase에 로그인하고 Firebase 호스팅에 배포하는 옵션이 표시됩니다. firebase login 명령어를 사용하여 Firebase에 로그인한 다음 콘솔로 계속을 클릭합니다. 이후 단계에서 Firebase 호스팅에 배포합니다.

Firebase 인증에 Google 로그인 사용 설정

사용자가 Google 계정으로 웹 앱에 로그인할 수 있도록 하려면 Google 로그인 방법을 사용합니다.

Google 로그인을 사용 설정해야 합니다.

  1. Firebase Console의 왼쪽 패널에서 빌드 섹션을 찾습니다.
  2. 인증을 클릭하고 해당하는 경우 시작하기를 클릭한 다음 로그인 방법 탭을 클릭합니다 (또는 여기를 클릭하여 로그인 방법 탭으로 바로 이동).
  3. Google 로그인 제공업체 사용 설정
  4. 앱의 공개용 이름을 Friendly Chat으로 설정하고 드롭다운 메뉴에서 프로젝트 지원 이메일을 선택합니다.
  5. 저장을 클릭합니다.

f96888973c3d00cc.png

Cloud Firestore 설정

웹 앱은 Cloud Firestore를 사용하여 채팅 메시지를 저장하고 새 채팅 메시지를 수신합니다.

Firebase 프로젝트에서 Cloud Firestore를 설정하는 방법은 다음과 같습니다.

  1. Firebase Console의 왼쪽 패널에서 빌드를 펼친 다음 Firestore 데이터베이스를 선택합니다.
  2. 데이터베이스 만들기를 클릭합니다.
  3. 데이터베이스 ID는 (default)로 설정된 채로 둡니다.
  4. 데이터베이스의 위치를 선택한 다음 다음을 클릭합니다.
    실제 앱의 경우 사용자와 가까운 위치를 선택해야 합니다.
  5. 테스트 모드로 시작을 클릭합니다. 보안 규칙에 관한 면책 조항을 읽습니다.
    이 Codelab의 후반부에서 데이터를 보호하는 보안 규칙을 추가합니다. 데이터베이스에 대한 보안 규칙을 추가하지 않은 채 앱을 공개적으로 배포하거나 노출하지 마세요.
  6. 만들기를 클릭합니다.

Firebase용 Cloud Storage 설정

웹 앱은 Firebase용 Cloud Storage를 사용하여 사진을 저장, 업로드, 공유합니다.

Firebase 프로젝트에서 Firebase용 Cloud Storage를 설정하는 방법은 다음과 같습니다.

  1. Firebase Console의 왼쪽 패널에서 빌드를 펼친 다음 스토리지를 선택합니다.
  2. 시작하기를 클릭합니다.
  3. 기본 Storage 버킷의 위치를 선택합니다.
    US-WEST1, US-CENTRAL1, US-EAST1의 버킷은 Google Cloud Storage의 '항상 무료' 등급을 활용할 수 있습니다. 다른 모든 위치의 버킷은 Google Cloud Storage 가격 책정 및 사용량을 따릅니다.
  4. 테스트 모드로 시작을 클릭합니다. 보안 규칙에 관한 면책 조항을 읽습니다.
    이 Codelab의 후반부에서 데이터를 보호하는 보안 규칙을 추가합니다. 스토리지 버킷에 대한 보안 규칙을 추가하지 않은 채 앱을 공개적으로 배포하거나 노출하지 마세요.
  5. 만들기를 클릭합니다.

4. Firebase 구성

appcheck-start 디렉터리에서 다음을 호출합니다.

firebase use --add

메시지가 표시되면 프로젝트 ID를 선택한 후 Firebase 프로젝트에 별칭을 지정합니다. 이 프로젝트의 경우 default라는 별칭을 지정하면 됩니다. 다음으로 Firebase와 호환되도록 로컬 프로젝트를 구성해야 합니다.

  1. Firebase Console의 프로젝트 설정으로 이동합니다.
  2. '내 앱' 카드에서 구성 객체가 필요한 앱의 닉네임을 선택합니다.
  3. Firebase SDK 스니펫 창에서 구성을 선택합니다.
  4. 구성 객체 스니펫을 복사한 다음 appcheck-start/hosting/src/firebase-config.js에 추가합니다. Codelab의 나머지 부분에서는 변수 이름을 config라고 가정합니다.

firebase-config.js

const config = {
  apiKey: "API_KEY",
  authDomain: "PROJECT_ID.firebaseapp.com",
  databaseURL: "https://PROJECT_ID.firebaseio.com",
  projectId: "PROJECT_ID",
  storageBucket: "PROJECT_ID.firebasestorage.app",
  messagingSenderId: "SENDER_ID",
  appId: "APP_ID",
  measurementId: "G-MEASUREMENT_ID",
};

동일한 appcheck-start 디렉터리에서 다음을 호출합니다.

firebase experiments:enable webframeworks

이렇게 하면 이 프로젝트가 빌드된 웹 프레임워크 지원을 사용할 수 있습니다.

이제 프로젝트를 실행하고 기본 프로젝트가 작동하는지 테스트할 준비가 되었습니다.

5. 앱 체크 없이 앱 사용해 보기

이제 앱을 구성하고 SDK를 설정했으므로 원래 설계된 대로 앱을 사용해 보세요. 먼저 모든 종속 항목을 설치합니다. 터미널에서 appcheck-start/hosting 디렉터리로 이동합니다. 이 디렉터리 내에서 npm install를 실행합니다. 이렇게 하면 프로젝트가 작동하는 데 필요한 모든 종속 항목이 가져옵니다. 현재 상태에서 앱을 시작하려면 firebase serve를 실행하면 됩니다. 앱에서 Google 계정으로 로그인하라는 메시지가 표시되면 로그인한 후 채팅에 채팅 메시지와 사진을 몇 개 게시해 봅니다.

이제 로컬에서 테스트했으므로 프로덕션에서 확인해 보겠습니다. firebase deploy를 실행하여 웹 애플리케이션을 웹에 배포합니다. 이 부분은 reCAPTCHA Enterprise 증명 제공업체에 대해 도메인을 구성해야 하므로 앱 체크가 실제로 작동하는 방식을 데모하는 데 중요한 단계입니다.

앱에서 제공하는 기본 기능을 사용하고 계시기를 바랍니다. 채팅 메시지 및 이와 같은 앱에서만 실행해야 하는 기타 모든 항목을 게시합니다. 현재 상태의 단점은 이전 단계의 앱 구성을 가진 모든 사용자가 백엔드 리소스에 액세스할 수 있다는 점입니다. Firestore 및 Cloud Storage 시스템에 적용된 보안 규칙은 계속 준수해야 하지만, 그 외에는 저장된 데이터를 쿼리, 저장, 액세스할 수 있습니다.

다음 몇 단계에서는 다음을 수행합니다.

  • 앱 체크 등록
  • 시정 조치 확인
  • 규칙 시행 시작

6. 앱 체크 및 시정 조치 사용 설정

먼저 프로젝트의 reCAPTCHA Enterprise 키를 가져와 앱 체크에 추가해 보겠습니다. 먼저 Google Cloud 콘솔의 reCAPTCHA Enterprise 섹션으로 이동합니다. 프로젝트를 선택하면 reCAPTCHA Enterprise API를 사용 설정하라는 메시지가 표시됩니다. API를 사용 설정하고 완료될 때까지 몇 분 정도 기다립니다. 그런 다음 엔터프라이즈 키 옆에 있는 키 만들기를 클릭합니다. 그런 다음 이 섹션에서 표시 이름을 지정하고 웹사이트 유형 키를 선택합니다. 앱이 호스팅되는 도메인을 지정해야 합니다. Firebase 호스팅에서 호스팅할 예정이므로 기본 호스팅 이름(일반적으로 ${YOUR_PROJECT_ID}.web.app)을 사용합니다. 호스팅 도메인은 Firebase Console의 호스팅 섹션에서 확인할 수 있습니다. 이 정보를 입력한 후 완료 및 키 만들기를 누릅니다.

reCAPTCHA 키 만들기 화면

완료되면 주요 세부정보 페이지 상단에 ID가 표시됩니다.

reCAPTCHA Enterprise 등록 창

이 ID를 클립보드에 복사합니다. 앱 체크에 사용하는 키입니다. 그런 다음 Firebase Console의 앱 체크 부분으로 이동하여 시작하기를 클릭합니다. 그런 다음 등록을 클릭한 다음 reCAPTCHA Enterprise를 클릭하고 복사한 ID를 reCAPTCHA Enterprise 사이트 키의 텍스트 상자에 입력합니다. 나머지 설정은 기본값으로 둡니다. 앱 검토 페이지는 다음과 같이 표시됩니다.

reCAPTCHA Enterprise 토큰을 등록하는 앱 체크 앱 창

확인되지 않고 시행되지 않은 요청

이제 Firebase Console에 등록된 키가 있으므로 firebase serve를 실행하여 브라우저에서 사이트를 실행하는 단계로 돌아갑니다. 이제 웹 앱이 로컬에서 실행되고 Firebase 백엔드에 대한 요청을 다시 시작할 수 있습니다. 요청이 Firebase 백엔드에 적용되므로 이러한 요청은 앱 체크에서 모니터링되지만 적용되지는 않습니다. 전송되는 요청의 상태를 확인하려면 Firebase Console의 앱 확인 페이지에 있는 API 탭의 Cloud Firestore 섹션으로 이동하세요. 아직 App Check를 사용하도록 클라이언트를 구성하지 않았으므로 다음과 같이 표시됩니다.

앱에 대한 확인되지 않은 클라이언트 요청이 100% 표시된 앱 체크 대시보드

백엔드에 확인되지 않은 요청이 100% 전달됩니다. 이 화면은 거의 모든 클라이언트 요청이 앱 체크가 통합되지 않은 클라이언트에서 발생한다는 것을 보여주므로 유용합니다.

이 대시보드는 몇 가지 사항을 나타낼 수 있습니다. 가장 먼저 모든 클라이언트 앱이 최신 버전의 클라이언트를 실행 중인지 확인할 수 있습니다. 그렇다면 애플리케이션의 실제 클라이언트의 액세스를 사용 중지할 필요 없이 앱 체크를 안전하게 적용할 수 있습니다. 앱 내에서 발생하지 않은 백엔드 액세스 시도 횟수도 알 수 있습니다. 개발자가 모르는 사이에 백엔드에 직접 쿼리하는 사용자일 수 있습니다. 요청이 확인되지 않았음을 확인했으므로 요청 확인을 진행하기 전에 백엔드에 확인되지 않은 요청이 있을 수 있는 사용자에게 어떤 일이 발생하는지 확인해야 합니다.

확인되지 않고 시행된 요청

이전 화면에서 시행 버튼을 누른 다음 메시지가 표시되면 시행을 다시 누릅니다.

적용 버튼이 강조표시된 확인되지 않은 측정항목 대시보드

이렇게 하면 앱 체크가 시행되기 시작합니다. 이제 선택한 증명 제공업체 (이 경우 reCAPTCHA Enterprise)를 통해 확인되지 않은 백엔드 서비스에 대한 요청이 차단됩니다. http://localhost:5000에서 실행 중인 웹 앱으로 돌아갑니다. 페이지를 새로고침하고 데이터베이스에서 데이터를 가져오려고 하면 아무 일도 일어나지 않습니다. Chrome 콘솔을 열어 오류를 읽으면 다음과 유사한 내용이 표시됩니다.

Uncaught Error in snapshot listener: FirebaseError: [code=permission-denied]: Missing or insufficient permissions.

Firebase 리소스에 대한 요청에서 유효한 증명 토큰을 전달하지 않은 요청을 앱 체크에서 차단한 것입니다. 당분간은 앱 체크 시행을 사용 중지할 수 있으며 다음 섹션에서는 프렌디 채팅 예에 reCAPTCHA Enterprise 앱 체크를 추가하는 방법을 살펴봅니다.

7. 사이트에 reCAPTCHA Enterprise 키 추가

애플리케이션에 엔터프라이즈 키를 추가할 예정입니다. 먼저 hosting/src/firebase-config.js를 열고 다음 코드 스니펫에 reCAPTCHA Enterprise 키를 추가합니다.

const reCAPTCHAEnterpriseKey = {
  // Replace with your recaptcha enterprise site key
  key: "Replace with your recaptcha enterprise site key"
};

완료되면 hosting/src/index.js를 열고 51번 줄에서 firebase-config.js의 가져오기를 추가하여 reCAPTCHA 키를 가져오고 reCAPTCHA Enterprise 제공업체를 사용할 수 있도록 앱 체크 라이브러리를 가져옵니다.

// add from here
 import {
   initializeAppCheck,
   ReCaptchaEnterpriseProvider,
 } from 'firebase/app-check';
// to here

// replace this line
import { getFirebaseConfig } from './firebase-config.js';
// with this line
import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';

그런 다음 다음 줄에서 앱 체크를 설정하는 함수를 만듭니다. 이 함수는 먼저 개발 환경에 있는지 확인하고, 있는 경우 로컬 개발에 사용할 수 있는 디버그 토큰을 출력합니다.

import { getFirebaseConfig, getReCaptchaKey } from './firebase-config.js';
// add from here
 function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
 }
// to here

이제 선택한 제공자(이 경우 reCAPTCHA Enterprise)와 함께 작동하도록 앱 체크를 초기화합니다. 그런 다음 백그라운드에서 App Check 토큰을 자동으로 새로고침해야 합니다. 이렇게 하면 App Check 토큰이 비활성화된 경우 사용자가 서비스와 상호작용할 때 지연이 발생하지 않습니다.

function setupAppCheck(app) {
   if(import.meta.env.MODE === 'development') {
     self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
   }
// add from here
   // Create a ReCaptchaEnterpriseProvider instance using your reCAPTCHA Enterprise
   // site key and pass it to initializeAppCheck().
   initializeAppCheck(app, {
     provider: new ReCaptchaEnterpriseProvider(getReCaptchaKey()),
     isTokenAutoRefreshEnabled: true // Set to true to allow auto-refresh.
   });
// to here
 }

마지막으로 앱이 초기화되었는지 확인한 후 방금 만든 setupAppCheck 함수를 호출해야 합니다. hosting/src/index.js 파일 하단에 최근에 추가한 메서드 호출을 추가합니다.

const firebaseApp = initializeApp(getFirebaseConfig());
// add from here
setupAppCheck(firebaseApp);
// to here
getPerformance();
initFirebaseAuth();
loadMessages();

먼저 로컬에서 테스트

먼저 로컬에서 애플리케이션을 테스트합니다. 아직 로컬에서 애플리케이션을 제공하고 있지 않다면 firebase serve를 실행합니다. 애플리케이션이 여전히 로컬에서 로드되지 않는 것을 확인할 수 있습니다. Firebase 도메인만 reCAPTCHA 증명 제공업체에 등록하고 localhost 도메인은 등록하지 않았기 때문입니다. localhost를 승인된 도메인으로 등록하면 사용자가 로컬 머신에서 로컬로 실행되는 애플리케이션에서 제한된 백엔드에 액세스할 수 있으므로 localhost를 승인된 도메인으로 등록해서는 안 됩니다. 대신 self.FIREBASE_APPCHECK_DEBUG_TOKEN = true를 설정했으므로 JavaScript 콘솔에서 다음과 유사한 줄을 확인해야 합니다.

App Check debug token: 55183c20-de61-4438-85e6-8065789265be. You will need to add it to your app's App Check settings in the Firebase console for it to work.

제공된 디버그 토큰 (예 : 55183c20-de61-4438-85e6-8065789265be)을 가져와 앱의 오버플로 메뉴 아래에 있는 앱 검사 구성에 연결합니다.

디버그 토큰 관리 위치를 나타내는 앱 체크 대시보드

기억할 수 있는 고유한 이름을 토큰에 지정하고 저장을 클릭합니다. 이 옵션을 사용하면 앱에서 클라이언트가 생성한 토큰을 사용할 수 있습니다. 이는 디버그 토큰을 생성하여 애플리케이션 내에 삽입하는 것보다 안전한 대안입니다. 앱 내에 토큰을 삽입하면 토큰이 실수로 최종 사용자에게 배포될 수 있으며, 최종 사용자가 개발자의 검사를 우회하여 이를 악용할 수 있습니다. 예를 들어 CI 환경에서 디버그 토큰을 배포하려면 이 문서에서 배포 방법을 자세히 알아보세요.

별칭으로 디버그 토큰을 채우는 샘플

Firebase Console에 디버그 토큰을 등록한 후에는 App Check 시행을 다시 사용 설정하고 터미널에서 firebase serve를 호출하여 앱 콘텐츠가 로컬에서 로드되는지 테스트할 수 있습니다. 이전에 입력한 데이터가 웹 애플리케이션의 로컬 버전에 제공되는 것을 볼 수 있습니다. 디버그 토큰이 포함된 메시지가 콘솔에 계속 표시됩니다.

프로덕션에서 사용해 보기

App Check가 로컬에서 작동하는지 확인한 후 웹 애플리케이션을 프로덕션에 배포합니다. 터미널에서 firebase deploy를 다시 호출하고 페이지를 새로고침합니다. 이렇게 하면 Firebase 호스팅에서 실행되도록 웹 애플리케이션이 패키징됩니다. 애플리케이션이 Firebase 호스팅에 호스팅되면 ${YOUR_PROJECT_ID}.web.app에서 애플리케이션을 방문해 보세요. JavaScript 콘솔을 열면 더 이상 디버그 토큰이 표시되지 않고 프로젝트에 채팅이 로드되는 것을 볼 수 있습니다. 또한 애플리케이션과 잠시 상호작용한 후 Firebase Console의 앱 체크 섹션으로 이동하여 애플리케이션에 대한 요청이 모두 확인됨으로 전환되었는지 확인할 수 있습니다.

8. 수고하셨습니다.

축하합니다. 웹 앱에 Firebase 앱 체크를 추가했습니다.

프로덕션 환경의 reCAPTCHA Enterprise 토큰을 처리하도록 Firebase Console을 설정하고 로컬 개발을 위해 디버그 토큰을 설정할 수도 있습니다. 이렇게 하면 앱이 승인된 클라이언트에서 Firebase 리소스에 계속 액세스할 수 있으며 애플리케이션 내에서 사기 행위가 발생하지 않습니다.

다음 단계

다음 문서를 확인하여 Firebase 앱 체크를 다음에 추가하세요.

참조 문서