데이터 API 작성기에서는 역할 기반 권한 부여 워크플로를 사용합니다. 인증 여부에 관계없이 들어오는 모든 요청이 역할에 할당됩니다. 역할은 시스템 역할 또는 사용자 역할일 수 있습니다. 그런 다음 할당된 역할은 요청된 엔터티에서 해당 역할에 사용할 수 있는 작업, 필드 및 정책을 이해하기 위해 구성에 지정된 정의된 권한 에 대해 확인됩니다.
사용자의 역할 확인
역할에는 기본 권한이 없습니다. 데이터 API 작성기가 역할을 결정하면, 엔터티 permissions가 그 역할에 맞는 actions을 정의해야 요청이 성공적으로 처리됩니다.
다음 역할 평가 매트릭스는 클라이언트가 Authorization: Bearer <token>을 보내는 JWT 전달자 공급자(예: EntraID/AzureAD 및 Custom)에 적용됩니다.
| 제공된 전달자 토큰 |
X-MS-API-ROLE 제공 |
토큰 roles 클레임에 있는 요청된 역할 |
효과적인 역할/결과 |
|---|---|---|---|
| 아니오 | 아니오 | N/A | Anonymous |
| 예(유효) | 아니오 | N/A | Authenticated |
| 예(유효) | 예 | 아니오 | 거부됨(403 금지됨) |
| 예(유효) | 예 | 예 |
X-MS-API-ROLE 값 |
| 예(유효하지 않음) | 어느 것이든 | N/A | 거부됨(401 권한 없음) |
이외의 AnonymousAuthenticated역할을 사용하려면 헤더가 X-MS-API-ROLE 필요합니다.
비고
요청은 인증된 보안 주체의 많은 역할과 연결할 수 있습니다. 그러나 데이터 API 작성기는 정확히 하나의 효과적인 역할의 컨텍스트에서 권한 및 정책을 평가합니다. 제공된 경우 X-MS-API-ROLE 헤더는 사용될 역할을 선택합니다.
공급자 참고 사항:
- EasyAuth 공급자(예
AppService: ): 전달자 토큰이 아닌 플랫폼 삽입 헤더(예:X-MS-CLIENT-PRINCIPAL)를 통해 인증을 설정할 수 있습니다. -
Simulator: 요청은 실제 토큰의 유효성을 검사하지 않고 개발/테스트를 위해 인증된 것으로 처리됩니다.
시스템 역할
시스템 역할은 데이터 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 작성기에서 사용자 역할의 컨텍스트에서 요청을 평가하려면 다음 두 가지 요구 사항을 충족해야 합니다.
- 인증된 보안 주체는 JWT
roles클레임과 같이 사용자의 역할 멤버 자격을 나열하는 역할 클레임을 포함해야 합니다. - 클라이언트 앱은 요청이 있는 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" ]
}
]
}
데이터 API 작성기에서는 단일 유효 역할의 컨텍스트에서 요청을 평가합니다. 요청이 인증되고 헤더가 제공되지 않는 X-MS-API-ROLE 경우 Data API Builder는 기본적으로 시스템 역할의 Authenticated 컨텍스트에서 요청을 평가합니다.
클라이언트 애플리케이션의 요청에 값X-MS-API-ROLE이 있는 HTTP 헤더 author 도 포함된 경우 요청은 역할의 author 컨텍스트에서 평가됩니다. 액세스 토큰 및 X-MS-API-ROLE HTTP 헤더를 포함하는 예제 요청:
curl -k -X 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" ]
}]
}
인증되지 않은 사용자와 인증된 사용자 모두에게 액세스 권한을 부여하려면 시스템 역할Anonymous 및 Authenticated)에 대한 사용 권한을 명시적으로 부여합니다.
읽기 작업을 인증된 사용자로만 제한해야 하는 경우 다음 권한 구성을 설정해야 하므로 인증되지 않은 요청이 거부됩니다.
"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 변형 및 필터의 경우 권한 구성은 여기에 설명된 대로 액세스 제어를 계속 적용합니다.
항목 수준 보안
데이터베이스 정책을 사용하면 행 수준에서 결과를 필터링할 수 있습니다. 정책은 데이터베이스가 평가하는 쿼리 조건자로 변환되어 사용자가 권한 있는 레코드에만 액세스하도록 합니다.
| 지원되는 작업 | 지원되지 않음 |
|---|---|
read, updatedelete |
create, execute |
비고
NoSQL용 Azure Cosmos DB는 현재 데이터베이스 정책을 지원하지 않습니다.
자세한 구성 단계, 구문 참조 및 예제는 데이터베이스 정책 구성을 참조하세요.
빠른 예
{
"role": "consumer",
"actions": [
{
"action": "read",
"policy": {
"database": "@item.ownerId eq @claims.userId"
}
}
]
}