Microsoft Foundry의 인증 및 권한 부여는 보안 주체가 ID를 증명하고 작업을 수행할 수 있는 권한을 얻는 방법을 제어합니다. Foundry는 각각 자체 인증 및 RBAC(역할 기반 액세스 제어) 화면을 사용하여 작업을 제어 평면(리소스 관리) 및 데이터 평면(런타임 사용)으로 나눕니다.
Foundry는 Microsoft Entra ID 및 API 키의 두 가지 인증 방법을 지원합니다. Microsoft Entra ID를 사용하면 조건부 액세스, 관리 ID 및 세분화된 RBAC를 사용할 수 있습니다. API 키는 빠른 프로토타입 생성을 위해 계속 사용할 수 있지만 사용자별 추적 기능이 부족합니다. 이 문서에서는 이러한 메서드를 비교하고, ID를 역할에 매핑하며, 일반적인 최소 권한 시나리오를 설명합니다.
중요합니다
프로덕션 워크로드에 Microsoft Entra ID를 사용하여 조건부 액세스, 관리 ID 및 최소 권한 RBAC를 사용하도록 설정합니다. API 키는 빠른 평가에 편리하지만 세분화된 액세스를 제공합니다.
필수 조건
- Azure 구독. 아직 없는 경우 무료 계정을 만들 수 있습니다.
- 사용자 지정 하위 도메인이 구성된 Microsoft Foundry 리소스입니다.
- Azure RBAC 개념 이해
- 역할을 할당하려면 적절한 범위에서 소유자 역할 또는 사용자 액세스 관리자 역할이 필요합니다.
- (선택 사항) 프로그래밍 방식 인증을 위해 설치된 Python용 Azure CLI 또는 Azure SDK입니다.
- (선택 사항) 코드 샘플용 Python 패키지:
pip install azure-identity requests
컨트롤 플레인 및 데이터 평면
Azure 작업은 컨트롤 플레인과 데이터 평면의 두 가지 범주로 나눕니다. Azure는 리소스 관리(컨트롤 플레인)를 운영 런타임(데이터 평면)과 구분합니다. 따라서 제어 평면을 사용하여 구독의 리소스를 관리하고, 데이터 평면을 활용하여 리소스 유형 인스턴스에서 제공되는 기능을 사용합니다. 컨트롤 플레인 및 데이터 평면에 대한 자세한 내용은 Azure 컨트롤 플레인 및 데이터 평면을 참조하세요. Foundry에서는 컨트롤 플레인 작업과 데이터 평면 작업을 명확하게 구분합니다. 다음 표에서는 두 가지 차이점, Foundry의 범위, 사용자의 일반적인 작업, 예제 도구 및 기능 및 각각을 사용할 권한 부여 화면을 설명합니다.
| 비행기 (assuming "Plane" refers to an airplane) | Foundry의 범위 | 일반적인 작업 | 예제 도구 | 권한 부여 화면 |
|---|---|---|---|---|
| 제어 평면 | 리소스, 프로젝트, 네트워킹, 암호화 및 연결 설정 및 구성 | 리소스 만들기 또는 삭제, 역할 할당, 키 회전, Private Link 설정 | Azure Portal, Azure CLI, ARM 템플릿, Bicep, Terraform | Azure RBAC 작업 |
| 데이터 평면 | 모델 유추, 에이전트 상호 작용, 평가 작업 및 콘텐츠 안전 호출 실행 및 사용 | 채팅 완료, 임베딩 생성, 미세 조정 작업 시작하기, 에이전트 메시지 보내기, 분석기 및 분류기 작업 | SDK, REST API, Foundry 포털 플레이그라운드 | Azure RBAC dataActions |
모든 Bicep, Terraform 및 SDK 샘플은 Foundry용 GitHub의 foundry 샘플 리포지토리 를 참조하세요.
다음 목록 및 다이어그램에서는 컨트롤 플레인과 데이터 평면 작업 간의 구분을 자세히 보여 줍니다. Foundry 내의 컨트롤 플레인 동작은 다음과 같습니다.
- Foundry 리소스 만들기
- Foundry 프로젝트 만들기
- 계정 기능 서버 만들기
- 프로젝트 기능 호스트 만들기
- 모델 배포
- 계정 및 프로젝트 연결 만들기
Foundry 내의 데이터 평면 작업에는 다음이 포함됩니다.
- 에이전트 구축
- 평가 실행
- 추적 및 모니터링
- Fine-tuning
다음 다이어그램에서는 RBAC(역할 기반 액세스 제어) 할당과 함께 Foundry의 컨트롤 플레인과 데이터 평면 분리의 보기 및 컨트롤 플레인 또는 데이터 평면 또는 둘 다에서 사용자가 가질 수 있는 액세스 권한을 보여 줍니다. 다이어그램에서 볼 수 있듯이 RBAC "작업"은 컨트롤 플레인과 연결되고 RBAC "dataActions"는 데이터 평면과 연결됩니다.
인증 방법
Foundry는 Microsoft Entra ID(토큰 기반, 키가 없는) 및 API 키를 지원합니다.
Microsoft Entra ID (마이크로소프트 엔트라 ID)
Microsoft Entra ID는 https://cognitiveservices.azure.com/.default에 범위가 지정된 OAuth 2.0 베어러 토큰을 사용합니다.
다음을 위해 Microsoft Entra ID를 사용합니다.
- 프로덕션 워크로드.
- 조건부 액세스, MFA(다단계 인증) 및 Just-In-Time 액세스.
- 최소 권한 RBAC 및 관리 ID 통합.
장점: 세분화된 역할 할당, 주체별 감사, 제어 가능한 토큰 수명, 자동 비밀 관리, 서비스용 관리 아이덴티티.
제한 사항: 초기 설정 복잡성이 높습니다. RBAC(역할 기반 액세스 제어)를 이해해야 합니다. Foundry의 RBAC에 대한 자세한 내용은 Microsoft Foundry에 대한 역할 기반 액세스 제어를 참조하세요.
API 키
API 키는 Foundry 리소스로 범위가 지정된 정적 비밀입니다.
API 키는 다음 용도로 사용합니다.
- 빠른 프로토타입 생성.
- 단일 비밀 회전이 허용되는 격리된 테스트 환경입니다.
장점: 간단하고 언어에 구애받지 않으며 토큰 획득이 필요하지 않습니다.
제한 사항: 사용자 ID를 표현할 수 없고, 범위를 세분화하기 어렵고, 감사하기가 어렵습니다. 일반적으로 엔터프라이즈 프로덕션 워크로드에서 허용되지 않으며 Microsoft에서 권장하지 않습니다.
키 없는 인증을 사용하도록 설정하는 방법에 대한 자세한 내용은 Microsoft Entra ID를 사용하여 키 없는 인증 구성을 참조하세요.
Microsoft Entra ID를 사용하여 인증(Python)
다음 예제에서는 라이브러리를 사용하여 azure-identity Microsoft Entra ID로 인증하고 Foundry 엔드포인트에 요청하는 방법을 보여줍니다.
from azure.identity import DefaultAzureCredential
import requests
# Create a credential object using DefaultAzureCredential
# This automatically uses environment variables, managed identity, or Azure CLI credentials
credential = DefaultAzureCredential()
# Get an access token for the Cognitive Services scope
token = credential.get_token("https://cognitiveservices.azure.com/.default")
# Use the token in your API request
headers = {
"Authorization": f"Bearer {token.token}",
"Content-Type": "application/json"
}
# Replace with your Foundry endpoint
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"
# Example: List deployments (adjust the path for your specific API)
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())
예상 출력: 모델 배포를 나열하는 JSON 응답 또는 자격 증명이 없거나 역할 할당이 구성되지 않은 경우 인증 오류입니다.
참조: DefaultAzureCredential | azure-identity 라이브러리
API 키로 인증(Python)
다음 예제에서는 API 키를 사용하여 인증하는 방법을 보여줍니다. 빠른 프로토타입 생성에만 이 방법을 사용합니다. 프로덕션에 Microsoft Entra ID를 사용하는 것이 좋습니다.
import requests
# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"
headers = {
"api-key": api_key,
"Content-Type": "application/json"
}
# Example: List deployments
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())
경고
API 키는 리소스에 대한 모든 권한을 제공하며 특정 사용자 또는 작업으로 범위를 지정할 수 없습니다. 키를 정기적으로 회전하고 소스 제어에 커밋하지 않도록 합니다.
예상 출력: 모델 배포를 나열하는 JSON 응답 또는 API 키가 잘못된 경우 401 오류가 발생합니다.
참조: API 액세스 키 회전
기능 지원 매트릭스
다음 행렬을 참조하여 Foundry에서 API 키와 Microsoft Entra ID를 지원하는 기능을 이해합니다.
| 기능 또는 특징 | API 키 | Microsoft Entra ID (마이크로소프트 엔트라 ID) | 비고 |
|---|---|---|---|
| 기본 모델 유추(채팅, 임베딩) | 네 | 네 | 완벽하게 지원됩니다. |
| 미세 조정 작업 | 네 | 네 | Entra ID는 개별 주체별 감사를 추가합니다. |
| 에이전트 서비스 | 아니오 | 네 | 관리 ID 도구 액세스에 Entra ID를 사용합니다. |
| 평가 | 아니오 | 네 | Entra ID를 사용합니다. |
| 콘텐츠 안전 분석 호출 | 네 | 네 | RBAC를 사용하여 위험 수준이 높은 작업을 제한합니다. |
| 일괄 분석 작업 (Content Understanding) | 네 | 네 | 확장성을 위해 권장되는 엔트라 ID입니다. |
| 포털 플레이그라운드 사용 | 네 | 네 | 플레이그라운드는 프로젝트 연결 모드를 사용합니다. |
| Private Link를 사용하여 네트워크 격리 | 네 | 네 | Entra ID는 조건부 액세스를 추가합니다. |
| 최소 권한을 제공하는 기본 제공 역할 및 사용자 지정 역할 | 아니오 | 네 | 키는 리소스당 전부를 갖거나 아니면 아예 갖지 않습니다. |
| 관리된 ID(시스템 또는 사용자 할당) | 아니오 | 네 | 비밀 없는 인증을 사용하도록 설정합니다. |
| 요청당 사용자 식별 | 아니오 | 네 | 토큰에는 테넌트 및 개체 ID가 포함됩니다. |
| 해지(즉시) | 키 회전 | 역할 제거 또는 주체 비활성화 | 짧은 토큰 수명이 적용됩니다. |
| 자동화 파이프라인 지원 | 예(비밀) | 예(서비스 주체 또는 관리 ID) | Entra ID는 비밀 키 회전을 줄입니다. |
| 어시스턴트 API | 네 | 네 | Entra ID를 사용하는 것이 좋습니다. |
| 일괄 유추 | 네 | 네 |
ID 유형
Azure 리소스 및 애플리케이션은 각각 특정 시나리오를 위해 설계된 다양한 ID 유형을 사용하여 인증합니다. 사용자 주체는 사람 사용자를 나타내고, 서비스 주체는 응용 프로그램 또는 자동화된 프로세스를 나타내며, 관리 ID는 Azure 리소스가 다른 서비스에 액세스할 수 있는 안전하고 자격 증명을 요구하지 않는 방법을 제공합니다. 이러한 차이점을 이해하면 대화형 로그인, 앱 간 통신 또는 워크로드 자동화에 적합한 ID를 선택할 수 있습니다.
Azure는 다음 ID 유형을 지원합니다.
| ID 형식 | Description |
|---|---|
| 사용자 주체 | Microsoft Entra ID의 개별 사용자 |
| 서비스 주체 (앱 등록) | 클라이언트 암호 또는 인증서를 사용하는 애플리케이션 ID |
| 관리 ID (시스템 할당) | 플랫폼에서 자동으로 관리되는 Azure 리소스 바인딩 ID입니다. |
| 관리 ID(사용자 할당) | 여러 리소스에 연결하는 독립 실행형 ID입니다. |
기본 제공 역할 개요
Foundry에서 기본 제공 역할을 사용하여 사용자에 대해 허용되는 작업을 구분합니다. 대부분의 기업은 기본 제공 역할에 대한 제어 및 데이터 평면 작업의 분리를 원합니다. 다른 사용자는 결합된 데이터 및 컨트롤 플레인 역할이 필요한 역할 할당 수를 최소화할 것으로 예상합니다. 다음 표에서는 시나리오 및 각 시나리오에 가장 적합한 기본 제공 Foundry 역할을 나열합니다.
| 시나리오 | 일반적인 기본 제공 역할 | 비고 |
|---|---|---|
| 미리 배포된 모델을 사용하여 에이전트 빌드 | Azure AI 사용자 | 데이터 평면 사용량만; 관리 쓰기가 없습니다. |
| 배포 관리 또는 모델 미세 조정 | Azure AI 프로젝트 관리자 | 모델 배포 만들기 및 업데이트를 포함합니다. |
| 키 회전 또는 리소스 관리 | Azure AI 계정 소유자 | 높은 권한; 최소 권한에 대한 사용자 지정 역할을 고려합니다. |
| 리소스 관리, 배포 관리, 에이전트 빌드 | Azure AI 소유자 | 컨트롤 플레인과 데이터 평면 액세스가 모두 필요한 사용자를 위한 높은 권한의 셀프 서비스 역할입니다. 관찰 가능성이 필요한 경우 Azure Monitor 판독기와 결합합니다. |
| 관찰성, 추적, 모니터링 | Azure AI 사용자(최소) | Application Insights에 Azure Monitor 판독기 추가 |
기본 제공 역할 및 컨트롤 및 데이터 평면 작업의 분석을 이해하려면 다음 다이어그램을 검토합니다.
팁 (조언)
기본 제공 역할이 사용 사례에 대해 초과 권한을 부여하는 경우 사용자 지정 역할을 만듭니다.
Microsoft Entra ID 설정
Foundry에서 Entra ID 인증을 설정하는 방법에 대한 개략적인 지침은 키 없는 인증 구성을 참조하세요.
Microsoft Foundry 리소스에 사용자 지정 하위 도메인이 구성되어 있는지 확인합니다. 사용자 지정 하위 도메인을 참조하세요. 토큰 기반 인증에는 사용자 지정 하위 도메인이 필요합니다.
각 주체에 필요한 기본 제공 또는 사용자 지정 역할을 할당합니다. 역할을 할당하려면 대상 범위에서 소유자 또는 사용자 액세스 관리자 역할이 필요합니다. 일반적인 역할 할당:
- Azure AI 사용자: 미리 배포된 모델을 빌드하고 테스트해야 하는 개발자를 위한 것입니다.
- Azure AI 프로젝트 관리자: 프로젝트를 만들고 배포를 관리해야 하는 팀 리더의 경우
- Azure AI 계정 소유자: 전체 리소스 관리가 필요하고 데이터 평면 액세스를 위해 Azure AI 사용자를 조건부로 할당할 수 있는 관리자의 경우
- Azure AI 소유자: 전체 리소스 관리 및 데이터 평면 액세스가 모두 필요한 사용자입니다. Azure AI 사용자 역할을 할당하는 CLI 명령 예제:
az role assignment create \ --assignee <principal-id> \ --role "Azure AI User" \ --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>역할 할당을 확인하려면 역할을 실행하고
az role assignment list --assignee <principal-id> --scope <resource-scope>출력에 표시되는지 확인합니다.(선택 사항) 서비스 주체의 경우 앱 등록을 만들고, 클라이언트 암호 또는 인증서를 추가하고, 테넌트 ID, 클라이언트 ID, 비밀 또는 인증서를 기록해 둡니다.
(선택 사항) 관리 ID의 경우 호출 서비스에서 시스템 할당 ID를 사용하도록 설정하거나 사용자 할당 ID를 연결한 다음 Foundry 리소스에서 역할을 할당합니다.
모든 호출자가 토큰 인증을 사용한 후 키 기반 인증을 제거합니다. 필요에 따라 배포 템플릿에서 로컬 인증을 사용하지 않도록 설정합니다.
참조:Azure 역할 할당 | Foundry에 대한 역할 기반 액세스 제어
일반적인 인증 오류 문제 해결
| 오류 | 원인 | 해결 방법 |
|---|---|---|
| 401 권한 없음 | 누락되거나 만료된 토큰입니다. 잘못된 API 키 | 토큰 획득 범위가 https://cognitiveservices.azure.com/.default인지 확인합니다. 키 기반 인증을 사용하는 경우 API 키를 다시 생성합니다. |
| 403 금지됨 | 누락된 RBAC 역할 할당 | 리소스 또는 프로젝트 범위에서 적절한 기본 제공 역할(예: Azure AI 사용자)을 할당합니다. |
| AADSTS700016 | 테넌트에서 애플리케이션을 찾을 수 없음 | 앱 등록이 올바른 테넌트에 있고 클라이언트 ID가 올바른지 확인합니다. |
| 사용자 지정 하위 도메인 필요 | 리소스는 사용자 지정 하위 도메인 대신 지역 엔드포인트를 사용합니다. | Foundry 리소스에서 사용자 지정 하위 도메인 을 구성합니다. 토큰 기반 인증에는 사용자 지정 하위 도메인이 필요합니다. |