데이터 API 작성기에서는 역할 기반 권한 부여 워크플로를 사용합니다. 인증 여부에 관계없이 들어오는 모든 요청이 역할에 할당됩니다. 역할은 시스템 역할 또는 사용자 역할일 수 있습니다. 그런 다음 할당된 역할은 요청된 엔터티에서 해당 역할에 사용할 수 있는 작업, 필드 및 정책을 이해하기 위해 구성에 지정된 정의된 권한 에 대해 확인됩니다.
사용자의 역할 확인
role에는 기본 권한이 없습니다. Data API 작성기에서 규칙을 결정하면 요청이 성공하려면 엔터티 permissions 가 해당 역할을 정의 actions 해야 합니다.
| 제공된 토큰 |
x-ms-api-role 제공 |
x-ms-api-role 토큰에서 |
결과로 나타나는 역할 |
|---|---|---|---|
| 아니오 | 아니오 | 아니오 | anonymous |
| 예 | 아니오 | 아니오 | authenticated |
| 예 | 예 | 아니오 | 예외 |
| 예 | 예 | 예 |
x-ms-api-role 값 |
다른 역할로서 anonymous 또는 authenticated가 아닌 경우, x-ms-api-role 헤더가 필요합니다.
비고
요청에는 하나의 역할만 있을 수 있습니다. 토큰이 여러 역할을 나타내더라도, x-ms-api-role 값은 요청에 할당될 역할을 선택합니다.
시스템 역할
시스템 역할은 데이터 API 작성기에서 인식하는 기본 제공 역할입니다. 시스템 역할은 액세스 토큰에 표시된 요청자의 역할 멤버 자격에 관계없이 요청자에게 자동으로 할당됩니다. 다음과 같은 두 가지 시스템 역할이 anonymousauthenticated있습니다.
익명 시스템 역할
anonymous 시스템 역할은 인증되지 않은 사용자가 실행한 요청에 할당됩니다. 인증되지 않은 액세스가 필요한 경우 런타임 구성 정의 엔터티는 역할에 대한 anonymous 권한을 포함해야 합니다.
예시
다음 데이터 API 작성기 런타임 구성은 Book 엔터티에 대한 anonymous 액세스를 포함하도록 시스템 역할을 명시적으로 구성하는 방법을 보여 줍니다.
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ]
}
]
}
클라이언트 애플리케이션이 인증되지 않은 사용자를 대신하여 Book 엔터티에 액세스하는 요청을 보내면 앱에 HTTP 헤더가 Authorization 포함되지 않아야 합니다.
인증된 시스템 역할
authenticated 시스템 역할은 인증된 사용자가 실행한 요청에 할당됩니다.
예시
다음 데이터 API 작성기 런타임 구성은 Book 엔터티에 대한 authenticated 액세스를 포함하도록 시스템 역할을 명시적으로 구성하는 방법을 보여 줍니다.
"Book": {
"source": "books",
"permissions": [
{
"role": "authenticated",
"actions": [ "read" ]
}
]
}
사용자 역할
사용자 역할은 런타임 구성에서 설정한 ID 공급자 내에서 사용자에게 할당되는 비시스템 역할입니다. 데이터 API 작성기에서 사용자 역할의 컨텍스트에서 요청을 평가하려면 다음 두 가지 요구 사항을 충족해야 합니다.
- 클라이언트 앱 제공 액세스 토큰에는 사용자의 역할 멤버 자격을 나열하는 역할 클레임이 포함되어야 합니다.
- 클라이언트 앱은 요청이 있는 HTTP 헤더
X-MS-API-ROLE를 포함하고 헤더의 값을 원하는 사용자 역할로 설정해야 합니다.
역할 평가 예제
다음 예제는 Data API Builder 런타임 구성에 포함된 Book 엔터티에 대한 요청을 다음과 같이 보여 줍니다.
"Book": {
"source": "books",
"permissions": [
{
"role": "anonymous",
"actions": [ "read" ]
},
{
"role": "authenticated",
"actions": [ "read" ]
},
{
"role": "author",
"actions": [ "read" ]
}
]
}
Static Web Apps에서 사용자는 기본적으로 익명 역할의 멤버입니다. 사용자가 인증된 경우, 사용자는 anonymous 역할 및 authenticated 역할의 구성원입니다.
클라이언트 앱이 Static Web Apps 데이터베이스 연결(미리 보기)을 사용하여 배포된 데이터 API 작성기에 인증된 요청을 보내면 클라이언트 앱은 Static Web Apps가 JSON으로 변환하는 액세스 토큰을 제공합니다.
{
"identityProvider": "azuread",
"userId": "d75b260a64504067bfc5b2905e3b8182",
"userDetails": "username",
"userRoles": ["anonymous", "authenticated", "author"]
}
데이터 API 작성기에서는 단일 역할의 컨텍스트에서 요청을 평가하므로 기본적으로 시스템 역할 authenticated 의 컨텍스트에서 요청을 평가합니다.
클라이언트 애플리케이션의 요청에 값X-MS-API-ROLE이 있는 HTTP 헤더 author 도 포함된 경우 요청은 역할의 author 컨텍스트에서 평가됩니다. 액세스 토큰 및 X-MS-API-ROLE HTTP 헤더를 포함하는 예제 요청:
curl -k -r GET -H 'Authorization: Bearer ey...' -H 'X-MS-API-ROLE: author' https://localhost:5001/api/Book
중요합니다
클라이언트 앱의 roles 요청은 제공된 액세스 토큰의 클레임이 X-MS-API-ROLE 헤더에 나열된 역할을 포함하지 않을 경우 거부됩니다.
권한
사용 권한은 다음을 설명합니다.
- 역할 멤버 자격에 따라 엔터티에 대한 요청을 수행할 수 있는 사람은 누구인가요?
- 사용자가 수행할 수 있는 작업(만들기, 읽기, 업데이트, 삭제, 실행)은 무엇인가요?
- 특정 작업에 액세스할 수 있는 필드는 무엇입니까?
- 요청에 의해 반환된 결과에는 어떤 추가 제한이 있나요?
사용 권한을 정의하는 구문은 런타임 구성 문서에 설명되어 있습니다.
중요합니다
단일 엔터티의 권한 구성 내에 여러 역할이 정의될 수 있습니다. 그러나 요청은 단일 역할의 컨텍스트에서만 평가됩니다.
- 기본적으로 시스템 역할
anonymous또는authenticated - 포함되는 경우,
X-MS-API-ROLE에 설정된 역할이 HTTP 헤더에 포함됩니다.
기본적으로 보안 적용
기본적으로 엔터티에는 구성된 권한이 없으므로 아무도 엔터티에 액세스할 수 없습니다. 또한 Data API Builder는 런타임 구성에서 참조되지 않는 데이터베이스 개체를 무시합니다.
사용 권한을 명시적으로 구성해야 합니다.
엔터티에 대한 인증되지 않은 액세스를 허용하려면 엔터티 anonymous 의 권한에서 역할을 명시적으로 정의해야 합니다. 예를 들어 book 엔터티의 권한은 인증되지 않은 읽기 액세스를 허용하도록 명시적으로 설정됩니다.
"book": {
"source": "dbo.books",
"permissions": [{
"role": "anonymous",
"actions": [ "read" ]
}]
}
엔터티에 대한 권한 정의를 간소화하려면 역할에 대한 authenticated 특정 권한이 없는 경우 역할에 대해 anonymous 정의된 사용 권한이 사용된다고 가정합니다. 이전에 표시된 book 구성을 사용하면 익명 또는 인증된 사용자가 book 엔터티의 읽기 작업을 수행할 수 있습니다.
읽기 작업을 인증된 사용자로만 제한해야 하는 경우 다음 권한 구성을 설정해야 하므로 인증되지 않은 요청이 거부됩니다.
"book": {
"source": "dbo.books",
"permissions": [{
"role": "authenticated",
"actions": [ "read" ]
}]
}
엔터티는 anonymous 및 authenticated 역할에 대한 사용 권한이 필요하지 않으며, 또한 미리 설정되어 있지 않습니다. 엔터티의 권한 구성 내에서 하나 이상의 사용자 역할을 정의할 수 있으며, 정의되지 않은 다른 모든 역할, 시스템 또는 사용자 정의는 자동으로 액세스가 거부됩니다.
다음 예제에서 사용자 역할 administrator는 book 엔터티에 대해 정의된 유일한 역할입니다. 사용자가 administrator 역할의 멤버여야 하며, X-MS-API-ROLE 엔터티에서 작동하려면 HTTP 헤더에 그 역할을 book 포함해야 합니다.
"book": {
"source": "dbo.books",
"permissions": [{
"role": "administrator",
"actions": [ "*" ]
}]
}
비고
Azure Cosmos DB에서 Data API Builder를 사용할 때 GraphQL 쿼리에 대한 액세스 제어를 적용하려면 제공된 @authorize에서 지시문을 사용해야 합니다. 그러나 GraphQL 쿼리의 GraphQL 변형 및 필터의 경우 액세스 제어는 앞에서 설명한 대로 사용 권한 구성에 의해 계속 적용됩니다.
활동
액션은 역할 범위 내에서 개체의 접근성을 설명합니다. 작업은 개별적으로 또는 와일드카드 바로 가기( * 별표)를 사용하여 지정할 수 있습니다. 와일드카드 바로 가기는 엔터티 형식에 대해 지원되는 모든 작업을 나타냅니다.
- 테이블 및 뷰:
create,read,updatedelete - 저장 프로시저:
execute
작업에 대한 자세한 내용은 구성 파일 설명서를 참조하세요.
필드 액세스
작업에 액세스할 수 있는 필드를 구성할 수 있습니다. 예를 들어 작업에서 포함 및 read할 필드를 설정할 수 있습니다.
다음 예제에서는 free-access 역할의 사용자가 Column3에 대한 읽기 작업을 수행하지 못하도록 합니다.
Column3 GET 요청(REST 엔드포인트) 또는 쿼리(GraphQL 엔드포인트)에서 참조하면 거부된 요청이 발생합니다.
"book": {
"source": "dbo.books",
"permissions": [
{
"role": "free-access",
"actions": [
"create",
"update",
"delete",
{
"action": "read",
"fields": {
"include": [ "Column1", "Column2" ],
"exclude": [ "Column3" ]
}
}
]
}
]
}
비고
Azure Cosmos DB에서 Data API Builder를 사용할 때 GraphQL 쿼리에 대한 액세스 제어를 적용하려면 제공된 @authorize에서 지시문을 사용해야 합니다. 그러나 GraphQL 쿼리의 GraphQL 변형 및 필터의 경우 여기에 설명된 대로 권한 구성에 의해 액세스 제어가 계속 적용됩니다.
항목 수준 보안
데이터베이스 정책 식을 사용하면 결과를 더욱 제한할 수 있습니다. 데이터베이스 정책은 식을 데이터베이스에 대해 실행된 쿼리 조건자에 변환합니다. 데이터베이스 정책 식은 다음 작업에 대해 지원됩니다.
- 창조하다
- 읽기
- 업데이트
- 삭제
경고
저장 프로시저와 함께 사용되는 실행 작업은 데이터베이스 정책을 지원하지 않습니다 .
비고
데이터베이스 정책은 현재 NoSQL용 CosmosDB에서 지원되지 않습니다.
데이터베이스 정책에 대한 자세한 내용은 구성 파일 설명서를 참조하세요.
예시
타이틀이 read "샘플 consumer"인 레코드만 반환하도록 역할에 대한 작업을 제한하는 데이터베이스 정책입니다.
{
"role": "consumer",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.title eq 'Sample Title'"
}
}
]
}
관련 콘텐츠
- Azure 인증
- 로컬 인증