권한 부여 개요

권한 부여는 인증된 사용자가 Data API Builder 애플리케이션에서 수행할 수 있는 작업을 결정합니다. 인증은 사용자가 누구인지 확인하지만 권한 부여는 사용자가 액세스하고 수정할 수 있는 항목을 제어합니다.

데이터 API 작성기 에서는 역할 기반 권한 부여 워크플로를 사용합니다. 인증 여부에 관계없이 들어오는 모든 요청이 역할에 할당됩니다. 역할은 시스템 역할 또는 사용자 역할일 수 있습니다. 그런 다음 할당된 역할은 요청된 엔터티에서 해당 역할에 사용할 수 있는 작업, 필드 및 정책을 이해하기 위해 구성에 지정된 정의된 권한 에 대해 확인됩니다.

주요 권한 부여 개념

개체 권한

엔터티 수준에서 CRUD 작업(만들기, 읽기, 업데이트, 삭제)을 제어합니다. 각 역할은 특정 엔터티에 대한 특정 작업을 부여하거나 거부할 수 있습니다.

역할 기반 접근 제어

역할에 사용자를 할당하고 역할 멤버 자격에 따라 권한을 부여합니다. 역할은 유사한 액세스 패턴을 사용하여 대규모 사용자 그룹의 관리를 간소화합니다.

RLS(행 수준 보안)

사용자 ID 또는 세션 컨텍스트에 따라 데이터를 필터링합니다. 사용자는 데이터베이스 수준에서 적용되는 액세스 권한에 따라 자신이 허가된 행만 볼 수 있습니다.

API 정책

API 응답에 OData 조건자 및 필터를 적용합니다. 정책은 사용자 클레임 및 ID에 따라 쿼리 결과를 자동으로 제한합니다.

클레임 기반 권한 부여

액세스를 확인하려면 인증 토큰(예: 그룹, 역할, 사용자 지정 특성)의 클레임을 사용합니다. 클레임은 유연하고 세분화된 권한 결정을 제공합니다.

작동 방식

1. 사용자가 지원되는 인증 방법 중 하나를 사용하여 인증
2. 시스템은 인증 토큰(역할, 그룹, 조직 등)에서 클레임을 추출합니다.
3. 권한 부여 규칙은 사용자의 클레임 및 요청된 리소스에 대해 평가됩니다.
4. 엔터티 권한, 정책 및 행 수준 보안 규칙에 따라 액세스 권한이 부여되거나 거부됨

사용자의 역할 확인

역할에는 기본 권한이 없습니다. 데이터 API 작성기가 역할을 결정하면, 엔터티 permissions가 그 역할에 맞는 actions을 정의해야 요청이 성공적으로 처리됩니다.

다음 역할 평가 매트릭스는 클라이언트가 보내는 JWT(JSON Web Token) 전달자 공급자(예: EntraID/AzureAD 및Custom)에 적용됩니다.Authorization: Bearer <token>

이외의 AnonymousAuthenticated역할을 사용하려면 헤더가 X-MS-API-ROLE 필요합니다.

공급자 참고 사항:

• EasyAuth 공급자(예: AppService)의 경우 플랫폼 삽입 헤더(예: X-MS-CLIENT-PRINCIPAL)가 전달자 토큰 대신 인증을 설정합니다.
• Simulator: 요청은 실제 토큰의 유효성을 검사하지 않고 개발/테스트용으로 authenticated 처리됩니다.

시스템 역할

시스템 역할은 데이터 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 작성기에서 사용자 역할의 컨텍스트에서 요청을 평가하려면 다음 두 가지 요구 사항을 충족해야 합니다.

1. 인증된 보안 주체는 JWT roles 클레임과 같이 사용자의 역할 멤버 자격을 나열하는 역할 클레임을 포함해야 합니다.
2. 클라이언트 앱은 요청이 있는 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

Permissions

사용 권한은 다음을 설명합니다.

• 역할 멤버 자격에 따라 엔터티에 대한 요청을 수행할 수 있는 사람은 누구인가요?
• 사용자가 수행할 수 있는 작업(만들기, 읽기, 업데이트, 삭제, 실행)은 무엇인가요?
• 특정 작업에 액세스할 수 있는 필드는 무엇입니까?
• 요청에 의해 반환된 결과에는 어떤 추가 제한이 있나요?

사용 권한을 정의하는 구문은 런타임 구성 문서에 설명되어 있습니다.

기본적으로 보안 적용

기본적으로 엔터티에는 구성된 권한이 없으므로 아무도 엔터티에 액세스할 수 없습니다. 또한 Data API Builder는 런타임 구성에서 참조되지 않는 데이터베이스 개체를 무시합니다.

조치

액션은 역할 범위 내에서 개체의 접근성을 설명합니다. 작업은 개별적으로 또는 와일드카드 바로 가기( * 별표)를 사용하여 지정할 수 있습니다. 와일드카드 바로 가기는 엔터티 형식에 대해 지원되는 모든 작업을 나타냅니다.

• 테이블 및 뷰: 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" ]
              }
            }
          ]
        }
      ]
    }

데이터베이스 정책(항목 수준 보안)

데이터베이스 정책을 사용하면 행 수준에서 결과를 필터링할 수 있습니다. 정책은 데이터베이스가 평가하는 쿼리 조건자로 변환되어 사용자가 권한 있는 레코드에만 액세스하도록 합니다.

자세한 구성 단계, 구문 참조 및 예제는 데이터베이스 정책 구성을 참조하세요.

빠른 예

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

역할 상속

DAB 2.0은 역할 상속을 도입하므로 모든 역할에서 동일한 권한 블록을 반복할 필요가 없습니다. 상속 체인은 다음과 같습니다.

named-role → authenticated → anonymous

• 명시적으로 구성되지 않은 경우 엔터티는 authenticated에서 anonymous를 상속합니다.
• 구성되지 않은 명명된 역할은 authenticated로부터 상속되거나, anonymous도 없는 경우 authenticated로부터 상속됩니다.

사용 권한을 한 번 anonymous 정의할 수 있으며 모든 광범위한 역할은 중복 없이 동일한 액세스를 자동으로 가져옵니다.

{
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

이 구성에서는 anonymous, authenticated, 구성되지 않은 명명된 역할이 모두 Book를 읽을 수 있습니다.

상속이 적용된 후 모든 엔터티에 대해 확인된 권한을 표시하는 데 사용합니다 dab configure --show-effective-permissions .

사용 권한을 명시적으로 구성해야 합니다.

엔터티에 대한 인증되지 않은 액세스를 허용하려면 엔터티 Anonymous 의 권한에서 역할을 명시적으로 정의해야 합니다. 예를 들어 book 인증되지 않은 읽기 액세스를 허용하도록 엔터티의 사용 권한이 명시적으로 설정됩니다.

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Anonymous",
    "actions": [ "read" ]
  }]
}

읽기 작업을 인증된 사용자로만 제한해야 하는 경우 다음 권한 구성을 설정해야 하므로 인증되지 않은 요청이 거부됩니다.

"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": [ "*" ]
  }]
}

계층화된 보안 모델

데이터 API 작성기에서는 여러 권한 부여 계층을 사용합니다.

• 엔터티 수준: 액세스할 수 있는 엔터티 및 작업
• 정책 수준: 반환되는 데이터(클레임에 따라 필터링)
• 행 수준: 데이터베이스가 RLS를 통해 행 필터링을 적용합니다.
• API 수준: HTTP 헤더 및 요청 유효성 검사

다음 단계

• 역할 상속 - 역할 계층 구조 빌드
• API 정책 - 클레임에 따라 OData 필터 적용
• 행 수준 보안 - 데이터베이스 수준에서 데이터 필터링
• 모범 사례 - 보안 강화 지침