로컬 테스트를 위한 시뮬레이터 인증 구성

시뮬레이터 인증 공급자를 사용하면 ID 공급자를 구성하지 않고 로컬에서 역할 기반 권한을 테스트할 수 있습니다. 개발 중에 이를 사용하여 프로덕션에 배포하기 전에 권한 규칙이 올바르게 작동하는지 확인합니다.

로컬 인증 공급자 선택

개발 중에 프로덕션 ID 공급자를 구성하지 않고 인증 및 권한 부여를 테스트할 수 있습니다.

Provider	적합한 대상	비고
시뮬레이터	빠른 권한 테스트	개발 전용입니다. 모든 요청을 인증된 것으로 처리합니다. 기본값은 Authenticated 역할로 설정되며, X-MS-API-ROLE으로 재정의할 수 있습니다.
AppService	클레임 기반 테스트	EasyAuth를 사용자 지정 클레임과 함께 로컬에서 X-MS-CLIENT-PRINCIPAL로 시뮬레이션합니다. 자세한 내용은 App Service 인증 구성을 참조하세요.

인증 흐름

시뮬레이터 공급자는 모든 요청을 인증된 것으로 처리하므로 권한 부여 규칙 테스트에 집중할 수 있습니다.

Phase	어떻게 되나요?
요청 도착	개발자가 DAB에 HTTP 요청을 보냅니다.
역할 할당	DAB는 Authenticated (기본값) 또는 X-MS-API-ROLE 헤더의 역할을 할당합니다.
사용 권한 확인	DAB는 해당 역할에 대한 엔터티의 권한에 대해 요청을 평가합니다.
쿼리 실행	허용되는 경우 DAB는 데이터베이스를 쿼리하고 결과를 반환합니다.

중요합니다

시뮬레이터 공급자는 개발 전용입니다. 프로덕션 환경에서는 절대 사용하지 마세요. 모든 실제 인증을 무시합니다.

필수 조건

• 설치된 데이터 API 작성기 CLI(설치 가이드)
• 기존 dab-config.json에 엔터티가 하나 이상 있는 항목

빠른 참조

Setting	가치
Provider	Simulator
호스트 모드	development(필수)
기본 역할	Authenticated (자동으로 삽입)
역할 오버라이드 헤더	X-MS-API-ROLE
필요한 토큰	아니오
클레임 지원	제한됨(시스템 역할 Anonymous/Authenticated 만, 임의 클레임 없음)

1단계: 시뮬레이터 공급자 구성

인증 공급자를 시뮬레이터로 설정하고 개발 모드가 사용하도록 설정되어 있는지 확인합니다.

CLI

배쉬

# Enable development mode
dab configure \
  --runtime.host.mode development

# Set the Simulator provider
dab configure \
  --runtime.host.authentication.provider Simulator

명령 프롬프트

REM Enable development mode
dab configure ^
  --runtime.host.mode development

REM Set the Simulator provider
dab configure ^
  --runtime.host.authentication.provider Simulator

결과 구성

{
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

비고

시뮬레이터 공급자는 mode가 development로 설정된 경우에만 작동합니다. 프로덕션 모드에서 DAB는 시뮬레이터 공급자를 거부하고 시작에 실패합니다.

2단계: 엔터티 권한 구성

테스트하려는 역할에 대한 사용 권한을 정의합니다. 시스템 역할(Anonymous, Authenticated) 및 사용자 지정 역할을 테스트할 수 있습니다.

예: 여러 역할

배쉬

# Allow anonymous read access
dab update Book \
  --permissions "Anonymous:read"

# Allow authenticated users full read access
dab update Book \
  --permissions "Authenticated:read"

# Allow authors to create and update
dab update Book \
  --permissions "author:create,read,update"

# Allow admins full access
dab update Book \
  --permissions "admin:*"

명령 프롬프트

REM Allow anonymous read access
dab update Book ^
  --permissions "Anonymous:read"

REM Allow authenticated users full read access
dab update Book ^
  --permissions "Authenticated:read"

REM Allow authors to create and update
dab update Book ^
  --permissions "author:create,read,update"

REM Allow admins full access
dab update Book ^
  --permissions "admin:*"

결과 구성

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

3단계: 다른 역할 테스트

데이터 API 작성기를 시작하고 각 역할을 테스트하기 위한 요청을 보냅니다.

dab start

인증된 테스트(기본값)

특별한 헤더가 없으면 요청은 "역할"로서 Authenticated로 평가됩니다.

curl -X GET "http://localhost:5000/api/Book"

익명으로 테스트

헤더 X-MS-API-ROLE를 사용하여 Anonymous로 테스트합니다.

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous"

사용자 지정 역할로 테스트

헤더를 X-MS-API-ROLE 사용하여 사용자 지정 역할을 테스트합니다.

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: author"

비고

시뮬레이터를 사용하면 DAB가 헤더 값에 따라 사용 권한을 평가하므로 사용자 지정 역할 테스트가 효과적으로 작동합니다. 시스템 역할(Anonymous, Authenticated)은 항상 사용할 수 있습니다. 사용자 지정 역할 요청이 403을 반환하는 경우 역할 이름이 엔터티 권한과 정확히 일치하는지 확인합니다.

거부해야 하는 작업 테스트

역할에 대한 권한이 없는 작업을 시도합니다.

# This should fail—Anonymous can only read
curl -X POST "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Book", "author": "Test"}'

예상 응답: 403 Forbidden

테스트 시나리오

시뮬레이터를 사용하여 다음과 같은 일반적인 시나리오를 테스트합니다.

Scenario	테스트 방법
익명 액세스	X-MS-API-ROLE: Anonymous 설정
인증된 액세스	헤더 생략(기본값) 또는 설정 X-MS-API-ROLE: Authenticated
사용자 지정 역할 액세스	X-MS-API-ROLE: <role-name> 설정
거부된 작업	역할에 대한 권한이 없는 작업 요청
필드 제한	필드 수준 권한 구성 및 응답 필드 확인
역할 누락	오류 처리를 테스트하도록 설정 X-MS-API-ROLE: nonexistent

제한점

시뮬레이터 공급자에는 다음과 같은 제한 사항이 있습니다.

Limitation	해결 방법
사용자 지정 클레임 없음	X-MS-CLIENT-PRINCIPAL 헤더와 함께 AppService 공급자를 사용하십시오.
클레임이 있는 데이터베이스 정책 없음	AppService 공급자를 사용하여 정책 테스트
토큰 유효성 검사 없음	프로덕션을 위해 Entra 또는 사용자 지정 공급자로 전환
개발 모드만	프로덕션 환경에서 실제 공급자 사용

팁 (조언)

클레임을 사용하는 데이터베이스 정책(예: @claims.userId)을 테스트해야 하는 경우 대신 AppService 공급자 를 사용합니다. 헤더를 통해 사용자 지정 클레임을 X-MS-CLIENT-PRINCIPAL 제공할 수 있습니다.

프로덕션으로 전환

배포할 준비가 되면 시뮬레이터 공급자를 프로덕션 공급자로 바꿉다.

1. mode을(를) development에서 production로 변경
2. 선택한 공급자(providerSimulatorEntraID또는/AzureAD)로 변경 AppServiceCustom
3. 필요한 JWT 설정 구성(대상 그룹, 발급자)

{
  "runtime": {
    "host": {
      "mode": "production",
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
        }
      }
    }
  }
}

전체 구성 예제

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "Server=localhost;Database=Library;Trusted_Connection=true;TrustServerCertificate=true;"
  },
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

관련 콘텐츠

• 권한 부여 및 역할
• App Service 인증 구성
• Microsoft Entra ID 인증 구성
• 런타임 구성 참조