Python용 채팅 문서 보안 시작

아티클
06/15/2024

사용자 고유의 데이터로 RAG 패턴을 사용하여 채팅 애플리케이션을 빌드하는 경우 각 사용자가 자신의 권한에 따라 답변을 받는지 확인합니다. 이 문서의 프로세스에 따라 채팅 앱에 문서 액세스 제어를 추가합니다.

권한 있는 사용자는 채팅 앱의 문서에 포함된 답변에 액세스할 수 있어야 합니다.

필요한 인증 액세스 권한이 있는 답변이 있는 채팅 앱의 스크린샷.

권한이 없는 사용자는 볼 수 있는 권한이 없는 보안 문서의 답변에 액세스할 수 없어야 합니다.

사용자가 데이터에 액세스할 수 없음을 나타내는 답변이 있는 채팅 앱의 스크린샷.

참고 항목

이 문서에서는 문서의 예제 및 지침에 대한 기준으로 하나 이상의 AI 앱 템플릿을 사용합니다. AI 앱 템플릿은 AI 앱의 고품질 시작 지점을 보장하는 데 도움이 되는 잘 유지 관리되고 배포하기 쉬운 참조 구현을 제공합니다.

아키텍처 개요

문서 보안 기능이 없으면 엔터프라이즈 채팅 앱에는 Azure AI Search 및 Azure OpenAI를 사용하는 간단한 아키텍처가 있습니다. 답변은 Azure OpenAI GPT 모델의 응답과 함께 문서가 저장되는 Azure AI Search에 대한 쿼리에서 결정됩니다. 이 간단한 흐름에서는 사용자 인증이 사용되지 않습니다.

Azure OpenAI의 프롬프트 응답과 함께 문서가 저장되는 Azure AI Search에 대한 쿼리에서 결정된 답변을 보여 주는 아키텍처 다이어그램.

문서에 대한 보안을 추가하려면 엔터프라이즈 채팅 앱을 업데이트해야 합니다.

Microsoft Entra를 사용하여 채팅 앱에 클라이언트 인증을 추가합니다.
서버 쪽 논리를 추가하여 사용자 및 그룹 액세스 권한으로 검색 인덱스를 채웁니다.

Microsoft Entra ID로 인증한 다음, 해당 인증을 Azure AI Search에 전달하는 사용을 보여 주는 아키텍처 다이어그램

Azure AI Search는 네이티브 문서 수준 권한을 제공하지 않으며 사용자 권한에 따라 인덱스 내에서 검색 결과를 변경할 수 없습니다. 대신 애플리케이션에서 검색 필터를 사용하여 특정 사용자 또는 특정 그룹에서 문서에 액세스할 수 있도록 할 수 있습니다. 검색 인덱스 내에서 각 문서에는 사용자 또는 그룹 ID 정보를 저장하는 필터링 가능한 필드가 있어야 합니다.

권한 부여는 Azure AI Search에 기본적으로 포함되지 않으므로 사용자 또는 그룹 정보를 보관할 필드를 추가한 다음 일치하지 않는 문서를 필터링 해야 합니다. 이 기술을 구현하려면 다음을 수행해야 합니다.

문서 액세스 권한이 있는 사용자 또는 그룹의 세부 정보를 저장하는 전용 문서 액세스 제어 필드를 인덱스로 만듭니다.
문서의 액세스 제어 필드를 관련 사용자 또는 그룹 세부 정보로 채웁니다.
사용자 또는 그룹 액세스 권한이 변경되면 이 액세스 제어 필드를 업데이트합니다.
인덱스 업데이트가 인덱서로 예약된 경우 다음 인덱서 실행에서 변경 내용이 선택됩니다. 인덱서를 사용하지 않는 경우 수동으로 다시 인덱싱해야 합니다.

이 문서에서는 검색 관리자가 실행할 예제 스크립트를 사용하여 Azure AI Search에서 문서를 보호하는 프로세스를 수행할 수 있습니다. 스크립트는 단일 문서를 단일 사용자 ID와 연결합니다. 이러한 스크립트를 사용하고 사용자 고유의 보안 및 프로덕션화 요구 사항을 적용하여 요구 사항에 맞게 확장할 수 있습니다.

보안 구성 확인

이 솔루션은 이 샘플에서 문서 보안에 필요한 기능을 켜는 부울 환경 변수를 제공합니다.

매개 변수	목적
`AZURE_USE_AUTHENTICATION`	로 `true`설정하면 사용자가 채팅 앱 및 App Service 인증에 로그인할 수 있습니다. `Use oid security filter` 채팅 앱 개발자 설정에서 사용하도록 설정합니다.
`AZURE_ENFORCE_ACCESS_CONTROL`	로 설정 `true`하면 모든 문서 액세스에 대한 인증이 필요합니다. OID 및 그룹 보안에 대한 개발자 설정이 켜지고 비활성화되므로 UI에서 비활성화할 수 없습니다.
`AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS`	이 설정으로 `true`설정하면 액세스 제어가 필요한 경우에도 인증된 사용자가 액세스 제어가 할당되지 않은 문서를 검색할 수 있습니다. 이 매개 변수는 사용하도록 설정된 경우에만 사용해야 `AZURE_ENFORCE_ACCESS_CONTROL` 합니다.
`AZURE_ENABLE_UNAUTHENTICATED_ACCESS`	이 설정으로 `true`설정하면 액세스 제어가 적용되는 경우에도 인증되지 않은 사용자가 앱을 사용할 수 있습니다. 이 매개 변수는 사용하도록 설정된 경우에만 사용해야 `AZURE_ENFORCE_ACCESS_CONTROL` 합니다.

다음 섹션을 사용하여 이 샘플에서 지원되는 보안 프로필을 이해합니다. 이 문서에서는 Enterprise 프로필을 구성합니다.

Enterprise: 필수 계정 + 문서 필터

사이트의 각 사용자는 로그인해야 하며 사이트에는 모든 사용자에게 공개되는 콘텐츠가 포함되어 있습니다 . 문서 수준 보안 필터는 모든 요청에 적용됩니다.

환경 변수:

AZURE_USE_AUTHENTICATION=true
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
AZURE_ENFORCE_ACCESS_CONTROL=true

혼합 사용: 선택적 계정 + 문서 필터

사이트의 각 사용자는 로그인할 수 있으며 사이트에는 모든 사용자에게 공개되는 콘텐츠가 포함됩니다. 문서 수준 보안 필터는 모든 요청에 적용됩니다.

환경 변수:

AZURE_USE_AUTHENTICATION=true
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
AZURE_ENFORCE_ACCESS_CONTROL=true
AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

필수 조건

개발 컨테이너 환경은 이 문서를 완료하는 데 필요한 모든 종속성에서 사용할 수 있습니다. GitHub Codespaces(브라우저)에서 개발 컨테이너를 실행하거나 Visual Studio Code를 사용하여 로컬로 실행할 수 있습니다.

이 문서를 사용하려면 다음 필수 구성 요소가 필요합니다.

Azure 구독. 무료로 계정 만들기
Azure 계정 권한 - Azure 계정에 있어야 합니다.
- Microsoft Entra ID에서 애플리케이션을 관리할 수 있는 권한입니다.
- Microsoft.Authorization/roleAssignments/write 권한(예: 사용자 액세스 관리자 또는 소유자).
원하는 Azure 구독의 Azure OpenAI에 대한 액세스 권한. 현재 이 서비스에 대한 액세스 권한은 애플리케이션에서만 부여됩니다. https://aka.ms/oai/access에서 양식을 작성하여 Azure OpenAI에 대한 액세스를 신청할 수 있습니다.

선호하는 개발 환경에 따라 더 많은 필수 구성 요소가 필요합니다.

Codespaces(권장)
Visual Studio Code

GitHub 계정

개방형 개발 환경

이 문서를 완료하려면 모든 종속성이 설치된 개발 환경으로 지금 시작합니다.

GitHub Codespaces(권장)
Visual Studio Code

GitHub Codespaces는 사용자 인터페이스로 웹용 Visual Studio Code를 사용하여 GitHub에서 관리하는 개발 컨테이너를 실행합니다. 가장 간단한 개발 환경을 위해서는 GitHub Codespaces를 사용하여 이 문서를 완료하는 데 필요한 올바른 개발자 도구와 종속성을 미리 설치합니다.

Important

모든 GitHub 계정은 2개의 코어 인스턴스를 사용하여 매월 최대 60시간 동안 Codespaces를 무료로 사용할 수 있습니다. 자세한 내용은 GitHub Codespaces 월별 포함 스토리지 및 코어 시간을 참조하세요.

Azure-Samples/azure-search-openai-demo GitHub 리포지토리의 main 분기에 새 GitHub Codespace를 만드는 프로세스를 시작합니다.
개발 환경과 설명서를 동시에 사용하려면 다음 단추를 마우스 오른쪽 단추로 클릭하고 새 창에서 링크 열기를 선택합니다.
codespace 만들기 페이지에서 codespace 구성 설정을 검토한 다음, 새 codespace 만들기를 선택합니다.
codespace가 생성될 때까지 기다립니다. 이 프로세스에는 몇 분 정도 걸릴 수 있습니다.
화면 하단의 터미널에서 Azure 개발자 CLI를 사용하여 Azure에 로그인합니다.
```
azd auth login
```
인증 프로세스를 완료합니다.
이 문서의 나머지 작업은 이 개발 컨테이너의 컨텍스트에서 수행됩니다.

Visual Studio Code용 Dev Containers 확장을 사용하려면 로컬 컴퓨터에 Docker를 설치해야 합니다. 확장은 이 문서를 완료하기 위해 사전 설치된 올바른 개발자 도구 및 종속성과 함께 Docker 호스트를 사용하여 개발 컨테이너를 로컬로 호스팅합니다.

컴퓨터에 프로젝트용 새 로컬 디렉터리를 만듭니다.
```
mkdir my-intelligent-app && cd my-intelligent-app
```
해당 디렉터리에서 Visual Studio Code를 엽니다.
```
code .
```
Visual Studio Code에서 새 터미널을 엽니다.
다음 AZD 명령을 실행하여 GitHub 리포지토리를 로컬 컴퓨터로 가져옵니다.
```
azd init -t azure-search-openai-demo
```
명령 팔레트를 열고, 개발 컨테이너: 컨테이너에서 폴더 열기를 검색하여 선택하여 개발 컨테이너에서 프로젝트를 엽니다. 계속하기 전에 개발 컨테이너가 열릴 때까지 기다립니다.
Azure 개발자 CLI를 사용하여 Azure에 로그인합니다.
```
azd auth login
```
터미널에서 코드를 복사한 다음 브라우저에 붙여넣습니다. 지침에 따라 Azure 계정으로 인증합니다.
이 프로젝트의 나머지 연습은 이 개발 컨테이너의 컨텍스트에서 수행됩니다.

Azure CLI를 사용하여 필수 정보 가져오기

다음 Azure CLI 명령을 사용하여 구독 ID 및 테넌트 ID를 가져옵니다. 로 사용할 값을 복사합니다 AZURE_TENANT_ID.

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

테넌트의 조건부 액세스 정책에 대한 오류가 발생하면 조건부 액세스 정책이 없는 두 번째 테넌트가 필요합니다.

사용자 계정과 연결된 첫 번째 테넌트는 환경 변수에 AZURE_TENANT_ID 사용됩니다.
조건부 액세스가 없는 두 번째 테넌트는 환경 변수가 AZURE_AUTH_TENANT_ID Microsoft Graph에 액세스하는 데 사용됩니다. 조건부 액세스 정책을 사용하는 테넌트에 대해 조건부 액세스 정책 없이 두 번째 테넌트 ID를 찾거나 새 테넌트를 만듭니다.

환경 변수 설정

다음 명령을 실행하여 엔터프라이즈 프로필에 대한 애플리케이션을 구성합니다.

azd env set AZURE_USE_AUTHENTICATION true
azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
azd env set AZURE_ENFORCE_ACCESS_CONTROL true

다음 명령을 실행하여 테넌트(사용자가 호스트된 애플리케이션 환경에 로그인할 수 있는 권한을 부여)를 설정합니다. 테넌트 ID로 바꿉니다 <YOUR_TENANT_ID> .
```
azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
```

참고 항목

사용자 테넌트에 조건부 액세스 정책이 있는 경우 인증 테넌트를 지정해야 합니다.

Azure에 채팅 앱 배포

배포에는 Azure 리소스 만들기, 문서 업로드, Microsoft Entra ID 앱 만들기(클라이언트 및 서버) 및 호스팅 리소스에 대한 ID 설정이 포함됩니다.

다음 Azure 개발자 CLI 명령을 실행하여 Azure 리소스를 프로비전하고 소스 코드를 배포합니다.
```
azd up
```

다음 표를 사용하여 AZD 배포 프롬프트에 응답합니다.

prompt	답변
환경 이름	별칭 및 앱 `tjones-secure-chat`과 같은 식별 정보와 함께 짧은 이름을 사용합니다.
구독	리소스를 만들 구독을 선택합니다.
Azure 리소스의 위치	가까운 위치를 선택합니다.
위치: `documentIntelligentResourceGroupLocation`	가까운 위치를 선택합니다.
위치: `openAIResourceGroupLocation`	가까운 위치를 선택합니다.

앱이 배포된 후 5~10분 정도 기다렸다가 앱을 시작할 수 있습니다.

애플리케이션이 성공적으로 배포되면 터미널에 URL이 표시됩니다.
브라우저에서 채팅 애플리케이션을 열려면 (✓) Done: Deploying service webapp이라고 표시된 URL을 선택합니다.
앱 인증 팝업에 동의합니다.
채팅 앱이 표시되면 오른쪽 위 모서리에 사용자가 로그인되어 있음을 알 수 있습니다.
개발자 설정을 열고 이러한 옵션이 모두 선택되고 회색으로 표시됩니다(변경에 사용할 수 없음).
- oid 보안 필터 사용
- 그룹 보안 필터 사용
와 함께 What does a product manager do?카드를 선택합니다.
다음과 같은 답변을 얻을 수 있습니다. The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

사용자에 대한 문서에 대한 액세스 열기

정확한 문서에 대한 사용 권한을 설정하여 답변을 얻을 수 있습니다 . 여기에는 다음과 같은 몇 가지 정보가 필요합니다.

Azure Storage
- 계정 이름
- 컨테이너 이름
- 에 대한 Blob/문서 URL role_library.pdf
Microsoft Entra ID의 사용자 ID

이 정보가 알려지면 문서의 Azure AI Search 인덱 oids 스 필드를 업데이트합니다 role_library.pdf .

스토리지에 있는 문서의 URL 가져오기

.azure 프로젝트의 루트에 있는 폴더에서 환경 디렉터리를 찾아 해당 디렉터리로 .env 파일을 엽니다.
AZURE_STORAGE_ACCOUNT 항목을 검색하고 해당 값을 복사합니다.

다음 Azure CLI 명령을 사용하여 콘텐츠 컨테이너에서 role_library.pdf Blob의 URL을 가져옵니다.

az storage blob url \
    --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
    --container-name 'content' \
    --name 'role_library.pdf'

매개 변수	목적
--account-name	Azure Storage 계정 이름
--container-name	이 샘플의 컨테이너 이름은 다음과 같습니다. `content`
--name	이 단계의 Blob 이름은 다음과 같습니다. `role_library.pdf`

나중에 사용할 Blob URL을 복사합니다.

사용자 ID 가져오기

chap 앱에서 개발자 설정을 선택합니다.
ID 토큰 클레임 섹션에서 objectidentifier. 이를 다음 섹션에서는 .로 알려져 있습니다 USER_OBJECT_ID.

Azure Search에서 문서에 대한 사용자 액세스 제공

다음 스크립트를 사용하여 role_library.pdf 대한 Azure AI Search의 필드를 변경 oids 하여 액세스할 수 있습니다.

./scripts/manageacl.sh \
    -v \
    --acl-type oids \
    --acl-action add \
    --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
    --url <REPLACE_WITH_YOUR_DOCUMENT_URL>

매개 변수	목적
-v	자세한 정보 출력.
--acl-type	그룹 또는 사용자 개체 ID(OID): `oids`
--acl-action	검색 인덱스 필드에 추가 합니다. 기타 옵션으로는 `remove`, . `remove_alllist`
--acl	그룹 또는 사용자의 `USER_OBJECT_ID`
--url	Azure Storage의 파일 위치(예: `https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf`.) CLI 명령에서 URL을 따옴표로 묶지 마세요.

이 명령의 콘솔 출력은 다음과 같습니다.

Loading azd .env file from current environment...
Creating Python virtual environment "app/backend/.venv"...
Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents

필요에 따라 다음 명령을 사용하여 Azure AI Search에서 파일에 대한 권한이 나열되는지 확인합니다.

./scripts/manageacl.sh \
    -v \
    --acl-type oids \
    --acl-action list \
    --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
    --url <REPLACE_WITH_YOUR_DOCUMENT_URL>

매개 변수	목적
-v	자세한 정보 출력.
--acl-type	그룹 또는 사용자(oids): `oids`
--acl-action	검색 인덱스 필드를 나열 합니다 `oids`. 기타 옵션으로는 `remove`, . `remove_alllist`
--acl	그룹 또는 사용자의 `USER_OBJECT_ID`
--url	Azure Storage의 파일 위치(예: `https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf`.) CLI 명령에서 URL을 따옴표로 묶지 마세요.

이 명령의 콘솔 출력은 다음과 같습니다.

Loading azd .env file from current environment...
Creating Python virtual environment "app/backend/.venv"...
Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
[00000000-0000-0000-0000-000000000000]

출력의 끝에 있는 배열에는 USER_OBJECT_ID 포함되며, Azure OpenAI를 사용하여 답변에 문서가 사용되는지 여부를 확인하는 데 사용됩니다.

Azure AI Search에 USER_OBJECT_ID 포함되어 있는지 확인합니다.

Azure Portal을 열고 AI Search.
목록에서 검색 리소스를 선택합니다.
검색 관리 -> 인덱스를 선택합니다.
gptkbindex를 선택합니다.
보기 -> JSON 보기를 선택합니다.
JSON을 다음 JSON으로 바꿉다.
```
{
  "search": "*",
  "select": "sourcefile, oids",
  "filter": "oids/any()"
}
```
이렇게 하면 필드에 값이 oids 있는 모든 문서를 검색하고 필드와 oids 필드를 반환sourcefile합니다.
oid가 role_library.pdf 없는 경우 Azure Search 섹션의 문서에 대한 사용자 액세스 권한 제공으로 돌아가서 단계를 완료합니다.

문서에 대한 사용자 액세스 확인

단계를 완료했지만 정답이 보이지 않으면 Azure AI Search role_library.pdf에서 USER_OBJECT_ID 올바르게 설정되었는지 확인합니다.

채팅 앱으로 돌아갑니다. 다시 로그인해야 할 수도 있습니다.
Azure OpenAI 답변What does a product manager do?에서 콘텐츠가 role_library 사용되도록 동일한 쿼리를 입력합니다.
이제 역할 라이브러리 문서의 적절한 답변이 포함된 결과를 봅니다.

리소스 정리

Azure 리소스 정리

이 문서에서 만들어진 Azure 리소스는 Azure 구독에 요금이 청구됩니다. 앞으로 이러한 리소스가 필요하지 않을 것으로 예상되는 경우 추가 요금이 발생하지 않도록 삭제합니다.

다음 Azure 개발자 CLI 명령을 실행하여 Azure 리소스를 삭제하고 소스 코드를 제거합니다.

azd down --purge

GitHub Codespaces 환경을 삭제하면 계정에 대해 얻을 수 있는 코어당 무료 사용 권한을 최대화할 수 있습니다.

중요

GitHub 계정의 자격에 대한 자세한 내용은 GitHub Codespaces 월별 포함된 스토리지 및 코어 시간을 참조하세요.

GitHub Codespaces 대시보드(https://github.com/codespaces)에 로그인합니다.
Azure-Samples/azure-search-openai-demo GitHub 리포지토리에서 제공된 현재 실행 중인 Codespaces를 찾습니다.
codespace에 대한 상황에 맞는 메뉴를 열고 삭제를 선택합니다.

도움말 보기

이 샘플 리포지토리는 문제 해결 정보를 제공합니다.

문제 해결

이 섹션에서는 이 문서와 관련된 문제에 대한 문제 해결을 제공합니다.

인증 테넌트 제공

인증이 호스팅 애플리케이션과 별도의 테넌트에 있는 경우 다음 프로세스를 사용하여 해당 인증 테넌트를 설정해야 합니다.

다음 명령을 실행하여 인증 테넌트에 두 번째 테넌트를 사용하도록 샘플을 구성합니다.
```
azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
```
매개 변수 목적

AZURE_AUTH_TENANT_ID 설정된 경우 AZURE_AUTH_TENANT_ID 앱을 호스트하는 테넌트입니다.
다음 명령을 사용하여 솔루션을 다시 배포합니다.
```
azd up
```

다음을 통해 공유