액세스 제어

Implement authorization to protect player data and game resources.

읽는 시간 4분

최근 업데이트: 6달 전

UGS(Unity Gaming Services)의 액세스 제어를 사용하면 부정 행위자나 취약점 공격자로부터 UGS의 게임 상태와 로직을 방어할 수 있습니다. 액세스 제어(API 권한 부여라고도 함)는 게임 데이터와 리소스를 무단으로 액세스하거나 수정, 삭제하지 못하도록 제어하므로 게임을 보호하는 데 중요한 역할을 합니다. UGS의 API 권한 부여는 사용자가 인증된 후 수행할 수 있는 동작을 결정하는 프로세스입니다. 인증은 사용자가 본인임을 확인하는 프로세스입니다. 인증과 권한 부여를 함께 사용하면 API에 대한 액세스와 리소스에 대한 액세스를 안전하게 제어할 수 있습니다. UGS는 이 기술 자료에 설명된 API 권한 부여와 함께 사용할 수 있는 Authentication 솔루션을 제공합니다. 인증이 없으면 누구나 API에 액세스하여 무단으로 동작을 수행할 위험이 있습니다. 예를 들어, API를 통해 사용자가 민감한 정보를 조회하거나 데이터를 변경할 수 있지만 인증이 적용되지 않으면, 누구나 권한 없이 해당 정보에 액세스하거나 데이터를 변경할 수 있습니다. 인증은 사용자의 ID를 확인하고, 권한 부여는 사용자가 수행할 수 있는 동작을 제어합니다. 인증은 권한 부여가 제대로 작동하는 데 필요한 기반을 제공합니다. 인증은 API의 문을 여는 열쇠 역할을 하지만, 권한 부여는 사용자가 들어갈 수 있다면 무엇을 할 수 있는지를 결정합니다.

액세스 제어 작동 방식

UGS에서 액세스 제어는 리소스 정책을 사용하여 구성됩니다. UGS 서비스는 해당 서비스에 액세스할 수 있는 사람과 수행할 수 있는 동작에 대한 규칙을 적용합니다. 사용자가 UGS 서비스에 액세스하려고 시도할 때, 서비스는 구성된 정책에 따라 사용자의 ID를 확인하고 API 요청을 거부하거나 허용합니다. 리소스 정책은 문(statement)의 모음입니다. 문은 사용자의 ID(Principal 속성), 제한되거나 허용되는(Effect 속성) 동작(Action 속성), 정책이 적용되는 리소스(Resource 속성)에 따라 정의됩니다. 또한 정책에는 ‘Sid’ 속성(문 식별자)이 포함되어 있습니다. 이는 지정된 정책에 대한 사용자 정의 설명 이름으로, 영숫자 문자와 하이픈만 포함할 수 있습니다. 정책의 리소스는 URN(고유 리소스 이름)으로 정의되며, 일반적으로 URN의 컴포넌트를 구성하는 API 경로로 끝납니다. 리소스 정책은 프로젝트별 또는 플레이어별로 구성됩니다. 프로젝트 정책은 해당 프로젝트에 대해 UGS 서비스를 호출하는 모든 주체에 대해 평가됩니다. 플레이어 정책은 프로젝트와 개발 환경의 범위 내에서 개별 플레이어에 대해서만 평가됩니다. 다음은 Economy 서비스에서 유효한 URN의 예제입니다.


urn:ugs:economy:/v2/project/*/player/*/currencies/gold

이는 공통된 패턴을 공유하는 리소스 세트를 매치하기 위해 glob 패턴을 사용합니다. 이 URN의 다양한 컴포넌트는 다음과 같습니다.

URN 컴포넌트	설명
urn:	문자열이 URN임을 나타내는 접두어입니다.
ugs:	URN의 NID(네임스페이스 식별자)는 이 네임스페이스에서 URN을 관리하는 조직이나 그룹을 식별합니다. 이 경우 ‘ugs’는 이 URN을 생성한 그룹인 Unity Gaming Services를 의미합니다.
economy:	네임스페이스 내에서 UGS의 특정 영역을 식별하는 특정 명명 권한입니다.
/v2/project/	API의 버전과 URN이 적용하는 프로젝트를 식별하는 URN의 특정 세그먼트입니다.
*	모든 문자와 일치하는 첫 번째 glob 패턴입니다. 이는 모든 가능한 값을 나타내는 와일드카드입니다. 이 경우 ‘urn:ugs:economy:/v2/project/’로 시작하여 그 뒤에는 문자가 나오는 URN과 일치합니다.
/player/	URN이 적용되는 플레이어를 식별하는 URN의 특정 세그먼트입니다.
*	모든 문자와 일치하는 두 번째 glob 패턴입니다. 이 경우 ‘urn:ugs:economy:/v2/project/*/player/’로 시작하여 그 뒤에는 문자가 오는 URN과 일치합니다.
/currencies/gold	이는 URN이 적용되는 특정 통화 유형을 식별하는 URN의 특정 세그먼트입니다.

URN 일치는 glob 패턴을 사용하기 때문에, 위 URN은 다음과 같이 정의할 수도 있습니다.

urn:ugs:economy:/**/currencies/gold

액세스 제어 정책이 생성되지 않은 경우, 액세스 제어는 인증된 플레이어의 모든 인증된 API 호출을 기본적으로 허용합니다. 이는 다음 리소스 정책을 사용하여 설명할 수 있습니다.


{	"Sid": "allow-all-ugs",	"Effect": "Allow",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:*"},

다음 예제는 인증된 플레이어가 API 호출을 통해 Economy에서 금화를 읽을 수 있지만, 변경(쓰기)은 할 수 없도록 유효한 정책을 생성하는 방법을 보여 줍니다.


{	"Sid": "deny-economy-write-access",	"Effect": "Deny",	"Action": ["Write"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/v2/project/*/player/*/currency/gold"},

또는 인증된 플레이어가 Economy 내에서 모든 API에 액세스하지 못하도록 완전히 거부하려면 다음을 수행합니다.


{	"Sid": "deny-all-economy-access",	"Effect": "Deny",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:economy:*"},

액세스 제어 사용 방법

REST API 또는 UGS CLI를 사용하여 UGS의 리소스 정책을 생성할 수 있습니다. 이 정책은 한 번만 생성하면 되며, 인증된 호출자의 컨텍스트 내에서 각 API 호출에 대해 평가되고 적용됩니다.

예제 정책

플레이어가 Cloud Code 스크립트를 실행하지 못하도록 설정합니다.


{	"Sid": "deny-cloud-code-access",	"Effect": "Deny",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:cloud-code:/v1/projects/*/scripts/*"},

이 리소스 정책은 인증된 프로젝트에서 Cloud Code 스크립트의 모든 동작에 대한 플레이어의 액세스를 거부합니다. Cloud Code는 위 정책 문에서 ‘Write’ 동작에 해당하는 API에 대한 POST 요청으로 ‘execute’ API만 제공합니다. 다음은 Cloud Save에 대한 리소스 정책의 또 다른 예제입니다.


{	"Sid": "deny-cloud-save-data-write-access",	"Effect": "Deny",	"Action": ["Write"],	"Principal": "Player",	"Resource": "urn:ugs:cloud-save:/v1/data/projects/*/players/*/items**"},

이 리소스 정책은 해당 프로젝트의 모든 Cloud Save 데이터에 대해 인증된 플레이어의 쓰기 액세스를 거부합니다. 여기에는 사용자나 그룹의

Player

ID에 해당하는 항목 아래에 있는 모든 중첩 경로와 하위 폴더도 포함됩니다. 이는 플레이어가 Cloud Save에 직접 데이터를 작성하는 것을 효과적으로 방지합니다. 앞서 언급한 Cloud Code 정책과 이 정책을 결합하면, 개발자는 Cloud Code를 통해 Cloud Save에 데이터를 작성할 수 있고, Cloud Code 내에서 추가적인 게임 로직을 구현할 수 있습니다. 다음은 정책을 구성하는 다양한 컴포넌트와 그 기능입니다.

문 속성	허용 가능한 값	설명
Sid	영숫자 문자열, 예: `^[A-Za-z0-9][A-Za-z0-9_-]{5,59}$`	문 식별자입니다. 이 정책은 각 개발 환경마다 고유한 값을 가지며, 정책에 대해 사람이 읽을 수 있는 이름을 제공하기 위해 사용됩니다. 유효한 값은 5자에서 59자 사이여야 합니다. 예: `deny-cloud-save-data-write-access`
Effect	Allow, Deny	이 정책이 특정 리소스에 대한 액세스를 허용할지 거부할지 여부를 지정하는 데 사용됩니다.
동작	Write, Read, *	허용되거나 거부되는 액세스의 유형을 지정하는 데 사용됩니다. 이 동작은 UGS의 다양한 제품에 대해 고유합니다. Write 값은 일반적으로 UGS 서비스에서 상태를 변경할 수 있는 작업을 의미합니다. UGS API의 POST, PUT, PATCH, DELETE HTTP 동사는 이 카테고리에 속합니다. Read 값은 일반적으로 UGS 서비스에서 상태를 가져오는 작업을 의미합니다. UGS API의 GET HTTP 동사는 이 카테고리에 속합니다. * 값은 모든 허용 가능한 동작을 포함하는 약어입니다.
Principal	플레이어	정책이 적용되는 사용자의 ID를 지정하는 데 사용됩니다. Player는 현재 유일하게 허용되는 값입니다.
Resource	유효한 UGS URN	정책이 적용되는 리소스 또는 리소스들을 지정하는 데 사용됩니다. 예를 들어, 리소스는 `urn:ugs:cloud-save:/v1/data/projects//players//items**` 로 설정할 수 있습니다. 이는 프로젝트에 인증된 모든 플레이어의 Cloud Save 데이터와 일치하는 URN으로, 항목 아래의 모든 중첩 경로와 하위 경로를 포함합니다.

오류 응답

플레이어가 적절한 권한이 없는 리소스에 액세스하려고 시도할 경우, 상태 코드 403 Forbidden과 함께 오류 응답이 반환됩니다. 오류 응답의 정확한 형식은 적용된 액세스 제어 정책의 유형에 따라 달라집니다. 프로젝트 기반 정책에 따라 플레이어가 리소스에 액세스할 수 없도록 제한된 경우 오류 응답에는 다음 필드가 포함됩니다.


{  "title": "Forbidden",  "detail": "Access has been restricted",  "code": 56,  "status": 403,  "type": "https://services.docs.unity.com/docs/errors/#56"}

플레이어 기반 정책에 따라 플레이어가 리소스에 액세스할 수 없도록 제한된 경우 오류 응답에는 다음 필드가 포함됩니다.


{  "title": "Forbidden",  "detail": "Principal is not authorized to access resource",  "code": 57,  "status": 403,  "type": "https://services.docs.unity.com/docs/errors/#57"}

플레이어가 일시적으로 금지된 경우 오류 응답에는 금지 기간이 언제 만료되는지를 나타내는

expiresAt

필드도 포함됩니다.


{  "title": "Forbidden",  "detail": "Principal is not authorized to access resource",  "code": 57,  "status": 403,  "type": "https://services.docs.unity.com/docs/errors/#57",  "expiresAt": "2023-04-29T18:30:51.243Z"}

플레이어가 영구적으로 금지된 경우 오류 응답에는

expiresAt

필드가 포함되지 않습니다. 원활한 사용자 경험을 위해 애플리케이션 코드에서 이러한 오류 응답을 적절히 처리해야 합니다.

액세스 제어에서 정책 선택

액세스 제어 정책이 평가될 때는 가장 구체적인 규칙만 적용되고, 해당 규칙의 효과가 반영됩니다. 다음은 세 가지 예제 정책입니다.


{	"Sid": "deny-all-economy-access",	"Effect": "Deny",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:economy:*"},{	"Sid": "allow-economy-currencies-access",	"Effect": "Allow",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/v2/**/currencies/*"},{	"Sid": "deny-gold-currency-access-economy",	"Effect": "Deny",	"Action": ["Write"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/v2/**/currencies/gold"},

첫 번째 규칙은 Economy에 대한 모든 요청을 일반적으로 거부합니다.
두 번째 규칙은 Economy의
```
*/currencies/
```
API에 대한 모든 요청에 대해 읽기/쓰기 액세스를 허용합니다.
세 번째 규칙은 특히 Economy의
```
*/currencies/gold
```
API에 대한 쓰기 요청을 거부합니다.

*/currencies/silver

에 대한 요청이 있을 경우 두 번째 규칙이 첫 번째 규칙보다 더 구체적이므로

/currencies/*

허용 규칙이 적용됩니다.

*/currencies/gold

에 대한 요청이 있을 경우 세 번째 규칙이 가장 구체적으로 해당 요청에 일치하므로

*/currencies/gold

거부 규칙이 적용됩니다. 동일한 리소스를 나열하는 정책이 여러 개 있는 경우 항상 거부 효과가 우선 적용됩니다.

베스트 프랙티스

기본적으로 거부

모든 액세스를 거부하는 기본 정책으로 시작하고 특정 API나 리소스에 대한 액세스를 명시적으로 허용합니다.


{	"Sid": "deny-all-ugs-access",	"Effect": "Deny",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:*:/**"},

최소 권한 원칙

API나 리소스에 대해 필요한 최소한의 권한만 허용합니다.


{	"Sid": "allow-cloud-save-read-access",	"Effect": "Allow",	"Action": ["Read"],	"Principal": "Player",	"Resource": "urn:ugs:cloud-save:/v1/data/**/player/*/items**"},

세밀한 정책 정의

모든 API와 리소스가 아닌 특정 API 메서드와 리소스를 위한 정책을 생성합니다.


{	"Sid": "allow-economy-silver-readwrite-access",	"Effect": "Allow",	"Action": ["*"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/**/currencies/silver"},{	"Sid": "deny-economy-gold-write-access",	"Effect": "Deny",	"Action": ["Write"],	"Principal": "Player",	"Resource": "urn:ugs:economy:/**/currencies/gold"},

정기적 검토

게임의 현재 상태를 반영하고 불필요한 권한을 제거하기 위해 API 정책을 정기적으로 검토하고 업데이트합니다.

REST API

액세스 제어 API는 웹 엔드포인트 또는 REST API를 통해 액세스할 수 있습니다. REST API는 원하는 언어와 게임 개발 엔진을 사용해 워크플로를 자동화할 수 있는 유연성을 제공합니다. 자세한 내용은 액세스 제어 REST API 기술 자료를 참고하십시오. API 호출 인증에 대한 자세한 내용은 서비스 계정 인증 기술 자료를 참고하십시오. 다음 예제는 cURL 툴을 사용하여 REST API로 리소스 정책을 설정하는 방법을 보여 줍니다.


curl -X PATCH https://services.api.unity.com/access/v1/projects/{projectId}/environments/{environmentId}/resource-policy \--header 'Authorization: Basic YOUR_ENCODED_API_KEY' \--header 'Content-Type: application/json' \--data-raw '{     "statements": [    	{            	"Sid": "deny-cloud-save-write-access",            	"Effect": "Deny",            	"Action": ["Write"],            	"Principal": "Player",            	"Resource": "urn:ugs:cloud-save:*"    	}    ]}'

액세스 제어 구성 배포

구성을 적용하려면 액세스 제어 서비스에 구성을 배포해야 합니다.

에디터에서 배포

Unity 에디터에서 액세스 제어 구성을 배포하려면 먼저 필요한 패키지를 설치하고 Unity Gaming Services 프로젝트를 Unity 에디터에 연결해야 합니다.

프로젝트 연결

Unity Gaming Services 프로젝트를 Unity 에디터와 연결합니다. Unity Dashboard에서 UGS 프로젝트 ID를 확인할 수 있습니다.

Unity 에디터에서 Edit > Project Settings > Services를 선택합니다.
프로젝트를 연결합니다.
- 프로젝트에 Unity 프로젝트 ID가 없는 경우 다음 단계를 진행합니다.
  1. Create a Unity Project ID > Organizations를 선택한 다음 드롭다운 메뉴에서 조직을 선택합니다.
  2. Create project ID를 선택합니다.
- Unity 프로젝트 ID가 있는 경우 다음 단계를 진행합니다.
  1. Use an existing Unity project ID를 선택합니다.
  2. 드롭다운 메뉴에서 조직과 프로젝트를 선택합니다.
  3. Link project ID를 선택합니다.

Unity 프로젝트 ID가 표시되고 이제 Unity 서비스에 프로젝트가 연결됩니다.

UnityEditor.CloudProjectSettings.projectId

를 사용하여 Unity 에디터 스크립트에서 프로젝트 ID에 액세스할 수도 있습니다.

필수 패키지 설치

에디터에서 액세스 제어 구성을 생성하려면 다음 패키지를 설치해야 합니다.

참고

Unity - 매뉴얼: Package Manager 창을 확인하여 Unity 패키지 관리자 인터페이스를 익혀 두십시오.

위 패키지를 설치한 후 다음 단계에 따라 사용 가능한 패키지 목록에 패키지를 추가합니다.

Unity 에디터의 Package Manager 창에서 + (add) > **Add package by name...**을 선택합니다.
```
com.unity.services.deployment
```
를 입력합니다.
Add를 선택합니다.
```
com.unity.services.tooling
```
에도 같은 단계를 반복합니다.

구성 생성

액세스 구성을 생성하려면 다음 단계를 수행합니다.

Unity 에디터에서 Project 창을 오른쪽 클릭하고 Create > Services > Access Control Configuration을 선택합니다.
원하는 대로 구성의 이름을 지정합니다.
Enter 키를 누릅니다.

Window > Deployment를 선택하여 액세스할 수 있는 Deployment 창과 Project 창에서 새 구성을 볼 수 있습니다.

구성 편집

기존 액세스 제어 구성을 편집하는 두 가지 방법은 다음과 같습니다.

프로젝트 탭에서 기존 구성을 더블 클릭합니다.
Deployment 창에서 기존 구성을 찾아 오른쪽 클릭한 다음, 표시되는 메뉴에서 Open을 선택합니다.

CLI를 사용하여 배포

UGS 액세스 제어 CLI를 사용하여 액세스 제어 구성을 더 간편하게 관리하고 자동화할 수 있습니다.

UGS CLI 구성

다음 단계를 따라 UGS CLI를 시작합니다.

UGS CLI를 설치합니다.

다음과 같이 프로젝트 ID와 환경을 구성합니다.

ugs config set project-id <your-project-id>

ugs config set environment-name <your-environment-name>

액세스 제어와 개발 환경 관리에 필요한 역할을 사용하여 서비스 계정을 구성합니다. 인증 받기를 참고하십시오.

리소스 배포

다음 커맨드를 실행합니다.

ugs deploy <path-to-access-control-file>

기술 자료

Development

User Acquisition

Monetization

산업 분야