Firebase Cloud Storage 보안 규칙의 조건 사용

이 가이드에서는 Firebase 보안 규칙 언어의 핵심 구문 알아보기 가이드를 바탕으로 Cloud Storage에 대한 Firebase 보안 규칙에 조건을 추가하는 방법을 보여줍니다.

Cloud Storage 보안 규칙의 기본 구성 요소는 조건입니다. 조건이란 특정 작업을 허용할지 아니면 거부할지 여부를 결정하는 불리언 표현식입니다. 기본 규칙의 경우 true 및 false 리터럴을 조건으로 사용하면 원활하게 작동합니다. 하지만 Cloud Storage에 대한 Firebase 보안 규칙 언어를 사용하면 다음과 같은 작업이 가능한 좀 더 복잡한 조건을 작성할 수 있습니다.

사용자 인증 확인
수신 데이터의 유효성 검사

인증

Cloud Storage에 대한 Firebase 보안 규칙은 Firebase 인증과 통합되어 Cloud Storage에 강력한 사용자 기반 인증을 제공합니다. 이를 통해 Firebase 인증 토큰의 소유권에 따른 세밀한 액세스 제어가 가능합니다.

인증된 사용자가 Cloud Storage에 요청을 수행하면 request.auth 변수가 사용자의 uid(request.auth.uid) 및 Firebase 인증 JWT(request.auth.token)의 클레임으로 채워집니다.

또한 커스텀 인증을 사용하는 경우 추가 클레임이 request.auth.token 필드에 표시됩니다.

인증되지 않은 사용자가 요청을 수행하면 request.auth 변수는 null입니다.

이 데이터를 사용하여 인증을 통해 파일의 보안을 설정하는 일반적인 방법은 다음과 같습니다.

공개: request.auth 무시
인증 비공개: request.auth가 null이 아닌지 확인
사용자 비공개: request.auth.uid가 uid 경로와 같은지 확인
그룹 비공개: 커스텀 토큰의 클레임이 특정 클레임과 일치하는지 확인하거나 파일 메타데이터를 읽어 메타데이터 필드가 있는지 확인

공개

request.auth 컨텍스트를 고려하지 않는 모든 규칙은 사용자의 인증 컨텍스트를 고려하지 않으므로 public 규칙으로 간주될 수 있습니다. 이러한 규칙은 게임 자산, 사운드 파일 또는 기타 정적 콘텐츠와 같은 공개 데이터를 노출하는 데 유용합니다.

// Anyone to read a public image if the file is less than 100kB
// Anyone can upload a public file ending in '.txt'
match /public/{imageId} {
  allow read: if resource.size < 100 * 1024;
  allow write: if imageId.matches(".*\\.txt");
}

인증 비공개

애플리케이션의 특정 데이터를 인증된 사용자에게만 공개하고 비인증 사용자에게는 숨겨야 할 수 있습니다. 인증되지 않은 모든 사용자는 request.auth 변수가 null이므로 인증을 요구하려면 request.auth 변수가 있는지 확인하면 됩니다.

// Require authentication on all internal image reads
match /internal/{imageId} {
  allow read: if request.auth != null;
}

사용자 비공개

request.auth의 가장 일반적인 사용 사례는 프로필 사진 업로드, 개인 문서 조회와 같이 파일에 개별 사용자 단위로 권한을 부여하는 것입니다.

Cloud Storage의 파일에는 파일의 전체 '경로'가 있기 때문에 사용자가 제어하는 파일을 만들려면 규칙이 판정될 때 확인할 수 있는 고유한 사용자 식별 정보(예: 사용자의 uid)가 파일 이름 프리픽스에 있기만 하면 됩니다.

// Only a user can upload their profile picture, but anyone can view it
match /users/{userId}/profilePicture.png {
  allow read;
  allow write: if request.auth.uid == userId;
}

그룹 비공개

또 다른 일반적인 사용법은 여러 팀원이 공유 문서를 공동으로 작업하는 경우와 같이 객체에 대한 그룹 권한을 허용하는 것입니다. 여기에는 몇 가지 방법이 있습니다.

그룹 구성원에 대한 추가 정보(예: 그룹 ID)를 포함하는 Firebase 인증 커스텀 토큰 발급
파일 메타데이터에 그룹 정보(예: 그룹 ID 또는 승인된 uid 목록) 포함

이러한 데이터를 토큰이나 파일 메타데이터에 저장한 후 규칙 내에서 참조할 수 있습니다.

// Allow reads if the group ID in your token matches the file metadata's `owner` property
// Allow writes if the group ID is in the user's custom token
match /files/{groupId}/{fileName} {
  allow read: if resource.metadata.owner == request.auth.token.groupId;
  allow write: if request.auth.token.groupId == groupId;
}

요청 검증

업로드, 다운로드, 메타데이터 변경, 삭제는 Cloud Storage로 전송된 request를 사용하여 검증됩니다. 위에서 설명한 request.auth 객체의 사용자 고유 ID 및 Firebase 인증 페이로드 외에도 request 변수에는 요청이 이루어지는 파일 경로, 요청 수신 시간, 새 resource 값(쓰기 요청인 경우)이 포함됩니다.

또한 request 객체는 request.auth 객체에 사용자의 고유 ID 및 Firebase 인증 페이로드를 포함합니다. 자세한 내용은 문서의 사용자 기반 보안 섹션을 참조하세요.

다음은 request 객체의 전체 속성 목록입니다.

속성	유형	설명
`auth`	맵<문자열, 문자열>	사용자가 로그인하면 `uid`(사용자의 고유 ID) 및 `token`(Firebase 인증 JWT 클레임의 맵)을 제공합니다. 그렇지 않으면 `null`입니다.
`params`	맵<문자열, 문자열>	요청의 쿼리 매개변수를 포함하는 맵입니다.
`path`	경로	요청이 이루어지는 경로를 나타내는 `path`입니다.
`resource`	맵<문자열, 문자열>	새 리소스 값이며 `write` 요청에만 있습니다.
`time`	타임스탬프	요청을 검증하는 서버 시간을 나타내는 타임스탬프입니다.

리소스 검증

규칙을 판정할 때 업로드, 다운로드, 수정 또는 삭제되는 파일의 메타데이터를 검증할 수도 있습니다. 이를 통해 특정 콘텐츠 유형의 파일만 업로드를 허용하거나 특정 크기보다 큰 파일만 삭제를 허용하는 등의 복잡하고 강력한 규칙을 만들 수 있습니다.

Cloud Storage에 대한 Firebase 보안 규칙은 resource 객체에 파일 메타데이터를 제공하며 이 객체는 Cloud Storage 객체에 노출된 메타데이터의 키-값 쌍을 포함합니다. read 또는 write 요청에서 이러한 속성을 검사하여 데이터 무결성을 확인할 수 있습니다.

업로드, 메타데이터 업데이트, 삭제 등의 write 요청에서는 현재 요청 경로에 있는 파일의 메타데이터를 포함하는 resource 객체뿐 아니라 쓰기가 허용된 경우 쓸 파일 메타데이터 중 일부를 포함하는 request.resource 객체도 사용할 수 있습니다. 이러한 두 값을 사용하여 데이터 무결성을 확인하거나 파일 형식, 크기 등의 애플리케이션 제한사항을 적용할 수 있습니다.

다음은 resource 객체의 전체 속성 목록입니다.

속성	유형	설명
`name`	문자열	객체의 전체 이름입니다.
`bucket`	문자열	객체가 속한 버킷의 이름입니다.
`generation`	정수	이 객체의 Google Cloud Storage 객체 세대
`metageneration`	정수	이 객체의 Google Cloud Storage 객체 메타세대
`size`	정수	객체 크기(바이트)입니다.
`timeCreated`	타임스탬프	객체 생성 시간을 나타내는 타임스탬프입니다.
`updated`	타임스탬프	객체의 마지막 업데이트 시간을 나타내는 타임스탬프입니다.
`md5Hash`	문자열	객체의 MD5 해시입니다.
`crc32c`	문자열	객체의 crc32c 해시입니다.
`etag`	문자열	이 객체에 연결된 etag입니다.
`contentDisposition`	문자열	이 객체에 연결된 콘텐츠 처리입니다.
`contentEncoding`	문자열	이 객체에 연결된 콘텐츠 인코딩입니다.
`contentLanguage`	문자열	이 객체에 연결된 콘텐츠 언어입니다.
`contentType`	문자열	이 객체에 연결된 콘텐츠 유형입니다.
`metadata`	맵<문자열, 문자열>	개발자가 추가로 지정한 커스텀 메타데이터의 키-값 쌍입니다.

request.resource는 generation, metageneration, etag, timeCreated, updated만 제외하고 이러한 속성을 모두 포함합니다.

Cloud Firestore로 개선

Cloud Firestore의 문서에 액세스하여 다른 승인 기준을 평가할 수 있습니다.

보안 규칙에서 firestore.get() 및 firestore.exists() 함수를 사용하여 수신된 요청을 Cloud Firestore의 문서와 비교할 수 있습니다. firestore.get() 및 firestore.exists() 함수에는 문서 경로 전체를 지정해야 합니다. 변수를 사용하여 firestore.get() 및 firestore.exists()의 경로를 작성하는 경우 $(variable) 구문을 사용하여 변수를 명시적으로 이스케이프해야 합니다.

아래 예에는 파일에 대한 읽기 액세스를 특정 클럽의 멤버로 제한하는 규칙이 있습니다.

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{club}/files/{fileId} {
      allow read: if club in
        firestore.get(/databases/(default)/documents/users/$(request.auth.id)).memberships
    }
  }
}

다음 예에서는 사용자의 친구만 사진을 볼 수 있습니다.

service firebase.storage {
  match /b/{bucket}/o {
    match /users/{userId}/photos/{fileId} {
      allow read: if
        firestore.exists(/databases/(default)/documents/users/$(userId)/friends/$(request.auth.id))
    }
  }
}

이러한 Cloud Firestore 함수를 사용하는 첫 번째 Cloud Storage 보안 규칙을 만들고 저장하면 Firebase Console 또는 Firebase CLI에 두 제품을 연결할 권한을 사용 설정하라는 메시지가 표시됩니다.

Firebase 보안 규칙 관리 및 배포에 설명된 대로 IAM 역할을 삭제하여 이 기능을 사용 중지할 수 있습니다.

데이터 검증

Cloud Storage에 대한 Firebase 보안 규칙은 contentType 및 size와 같은 파일 메타데이터 속성뿐만 아니라 파일 이름 및 경로 유효성 검사에도 사용할 수 있습니다.

service firebase.storage {
  match /b/{bucket}/o {
    match /images/{imageId} {
      // Only allow uploads of any image file that's less than 5MB
      allow write: if request.resource.size < 5 * 1024 * 1024
                   && request.resource.contentType.matches('image/.*');
    }
  }
}

커스텀 함수

Firebase 보안 규칙이 복잡해지면 조건 세트를 함수로 묶어 규칙 세트 전체에서 재사용할 수 있습니다. 보안 규칙에서는 커스텀 함수를 지원합니다. 커스텀 함수의 구문은 자바스크립트와 비슷하지만, Firebase 보안 규칙 함수는 도메인 특정 언어로 작성되며 다음과 같은 중요한 제한사항이 있습니다.

함수는 return 문 하나만 포함할 수 있습니다. 다른 로직은 포함할 수 없습니다. 예를 들어 루프를 실행하거나 외부 서비스를 호출할 수 없습니다.
함수는 정의된 범위에 속하는 함수와 변수에 자동으로 액세스할 수 있습니다. 예를 들어 service firebase.storage 범위 안에 정의된 함수는 resource 변수에 액세스할 수 있으며 Cloud Firestore의 경우에만 get(), exists() 등의 기본 제공 함수에 액세스할 수 있습니다.
함수는 다른 함수를 호출할 수 있지만 재귀 호출은 금지됩니다. 호출 스택 깊이는 최대 10으로 제한됩니다.
rules2 버전에서 함수는 let 키워드를 사용하여 변수를 정의할 수 있습니다. 함수는 여러 개의 let 바인딩을 가질 수 있지만 반환 구문으로 끝나야 합니다.

함수는 function 키워드로 정의되며 0개 이상의 인수를 취합니다. 예를 들어 위 예시에 사용한 두 가지 조건을 하나의 함수로 결합할 수 있습니다.

service firebase.storage {
  match /b/{bucket}/o {
    // True if the user is signed in or the requested data is 'public'
    function signedInOrPublic() {
      return request.auth.uid != null || resource.data.visibility == 'public';
    }
    match /images/{imageId} {
      allow read, write: if signedInOrPublic();
    }
    match /mp3s/{mp3Ids} {
      allow read: if signedInOrPublic();
    }
  }
}

Firebase 보안 규칙의 함수를 사용하면 규칙이 복잡해져도 쉽게 관리할 수 있습니다.

다음 단계

지금까지 조건에 대해 학습하며 규칙에 대해 자세히 알아봤습니다. 이제 다음과 같은 단계를 진행할 수 있습니다.

핵심 사용 사례를 처리하는 방법을 알아보고 규칙 개발, 테스트, 배포를 위한 워크플로를 살펴봅니다.

일반적인 시나리오를 다루는 규칙을 작성합니다.
안전하지 않은 규칙을 찾아 피해야 할 상황을 검토하며 지식을 쌓습니다.
Cloud Storage 에뮬레이터 및 전용 보안 규칙 테스트 라이브러리를 사용하여 규칙을 테스트합니다.
규칙 배포에 사용할 수 있는 방법을 검토합니다.