몰입형 리더 리소스 만들기 및 Microsoft Entra 인증 구성

  • 아티클

이 문서에서는 제공된 스크립트를 사용하여 몰입형 리더 리소스를 만드는 방법을 설명합니다. 이 스크립트는 Microsoft Entra 인증도 구성합니다. 이 스크립트를 사용하든 포털에서 몰입형 리더 리소스를 만들 때마다 Microsoft Entra 권한으로 구성해야 합니다.

스크립트는 필요한 모든 몰입형 리더 및 Microsoft Entra 리소스를 만들고 구성합니다. 그러나 Azure Portal에서 이미 만든 경우 기존 몰입형 리더 리소스에 대해 Microsoft Entra 인증을 구성할 수도 있습니다. 스크립트는 먼저 구독에서 기존 몰입형 리더 및 Microsoft Entra 리소스를 찾고 아직 없는 경우에만 만듭니다.

일부 고객의 경우 개발 및 프로덕션을 위해 또는 서비스가 배포된 다른 지역에 대해 여러 몰입형 리더 리소스를 만들어야 할 수 있습니다. 이러한 경우 다시 돌아와서 스크립트를 여러 번 사용하여 다른 몰입형 리더 리소스를 만들고 Microsoft Entra 권한으로 구성할 수 있습니다.

사용 권한

나열된 Azure 구독 소유자에는 몰입형 리더 리소스를 만들고 Microsoft Entra 인증을 구성하는 데 필요한 모든 권한이 있습니다.

소유자가 아닌 경우 다음과 같은 범위별 권한이 필요합니다.

  • Contributor. Azure 구독과 연결된 기여자 역할이 하나 이상 있어야 합니다.

    Screenshot of contributor built-in role description.

  • 애플리케이션 개발자. Microsoft Entra ID에 연결된 애플리케이션 개발자 역할이 있어야 합니다.

    Screenshot of the developer built-in role description.

자세한 내용은 Microsoft Entra 기본 제공 역할을 참조하세요.

PowerShell 리소스 설정

  1. Azure Cloud Shell을 열어 시작합니다. Cloud Shell이 왼쪽 위 드롭다운에서 또는 입력하여 PowerShell로 설정되어 있는지 확인합니다pwsh.

  2. 다음 코드 조각을 복사하여 셸에 붙여넣습니다.

    function Create-ImmersiveReaderResource(
    [Parameter(Mandatory=$true, Position=0)] [String] $SubscriptionName,
    [Parameter(Mandatory=$true)] [String] $ResourceName,
    [Parameter(Mandatory=$true)] [String] $ResourceSubdomain,
    [Parameter(Mandatory=$true)] [String] $ResourceSKU,
    [Parameter(Mandatory=$true)] [String] $ResourceLocation,
    [Parameter(Mandatory=$true)] [String] $ResourceGroupName,
    [Parameter(Mandatory=$true)] [String] $ResourceGroupLocation,
    [Parameter(Mandatory=$true)] [String] $AADAppDisplayName,
    [Parameter(Mandatory=$true)] [String] $AADAppIdentifierUri,
    [Parameter(Mandatory=$true)] [String] $AADAppClientSecretExpiration
)
{
    $unused = ''
    if (-not [System.Uri]::TryCreate($AADAppIdentifierUri, [System.UriKind]::Absolute, [ref] $unused)) {
        throw "Error: AADAppIdentifierUri must be a valid URI"
    }

    Write-Host "Setting the active subscription to '$SubscriptionName'"
    $subscriptionExists = Get-AzSubscription -SubscriptionName $SubscriptionName
    if (-not $subscriptionExists) {
        throw "Error: Subscription does not exist"
    }
    az account set --subscription $SubscriptionName

    $resourceGroupExists = az group exists --name $ResourceGroupName
    if ($resourceGroupExists -eq "false") {
        Write-Host "Resource group does not exist. Creating resource group"
        $groupResult = az group create --name $ResourceGroupName --location $ResourceGroupLocation
        if (-not $groupResult) {
            throw "Error: Failed to create resource group"
        }
        Write-Host "Resource group created successfully"
    }

    # Create an Immersive Reader resource if it doesn't already exist
    $resourceId = az cognitiveservices account show --resource-group $ResourceGroupName --name $ResourceName --query "id" -o tsv
    if (-not $resourceId) {
        Write-Host "Creating the new Immersive Reader resource '$ResourceName' (SKU '$ResourceSKU') in '$ResourceLocation' with subdomain '$ResourceSubdomain'"
        $resourceId = az cognitiveservices account create `
                        --name $ResourceName `
                        --resource-group $ResourceGroupName `
                        --kind ImmersiveReader `
                        --sku $ResourceSKU `
                        --location $ResourceLocation `
                        --custom-domain $ResourceSubdomain `
                        --query "id" `
                        -o tsv

        if (-not $resourceId) {
            throw "Error: Failed to create Immersive Reader resource"
        }
        Write-Host "Immersive Reader resource created successfully"
    }

    # Create an Microsoft Entra app if it doesn't already exist
    $clientId = az ad app show --id $AADAppIdentifierUri --query "appId" -o tsv
    if (-not $clientId) {
        Write-Host "Creating new Microsoft Entra app"
        $clientId = az ad app create --display-name $AADAppDisplayName --identifier-uris $AADAppIdentifierUri --query "appId" -o tsv
        if (-not $clientId) {
            throw "Error: Failed to create Microsoft Entra application"
        }
        Write-Host "Microsoft Entra application created successfully."

        $clientSecret = az ad app credential reset --id $clientId --end-date "$AADAppClientSecretExpiration" --query "password" | % { $_.Trim('"') }
        if (-not $clientSecret) {
            throw "Error: Failed to create Microsoft Entra application client secret"
        }
        Write-Host "Microsoft Entra application client secret created successfully."

        Write-Host "NOTE: To manage your Microsoft Entra application client secrets after this Immersive Reader Resource has been created please visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section" -ForegroundColor Yellow
    }

    # Create a service principal if it doesn't already exist
    $principalId = az ad sp show --id $AADAppIdentifierUri --query "id" -o tsv
    if (-not $principalId) {
        Write-Host "Creating new service principal"
        az ad sp create --id $clientId | Out-Null
        $principalId = az ad sp show --id $AADAppIdentifierUri --query "id" -o tsv

        if (-not $principalId) {
            throw "Error: Failed to create new service principal"
        }
        Write-Host "New service principal created successfully"

        # Sleep for 5 seconds to allow the new service principal to propagate
        Write-Host "Sleeping for 5 seconds"
        Start-Sleep -Seconds 5
    }

    Write-Host "Granting service principal access to the newly created Immersive Reader resource"
    $accessResult = az role assignment create --assignee $principalId --scope $resourceId --role "Cognitive Services Immersive Reader User"
    if (-not $accessResult) {
        throw "Error: Failed to grant service principal access"
    }
    Write-Host "Service principal access granted successfully"

    # Grab the tenant ID, which is needed when obtaining a Microsoft Entra token
    $tenantId = az account show --query "tenantId" -o tsv

    # Collect the information needed to obtain a Microsoft Entra token into one object
    $result = @{}
    $result.TenantId = $tenantId
    $result.ClientId = $clientId
    $result.ClientSecret = $clientSecret
    $result.Subdomain = $ResourceSubdomain

    Write-Host "`nSuccess! " -ForegroundColor Green -NoNewline
    Write-Host "Save the following JSON object to a text file for future reference."
    Write-Host "*****"
    if($clientSecret -ne $null) {

        Write-Host "This function has created a client secret (password) for you. This secret is used when calling Microsoft Entra to fetch access tokens."
        Write-Host "This is the only time you will ever see the client secret for your Microsoft Entra application, so save it now." -ForegroundColor Yellow
    }
    else{
        Write-Host "You will need to retrieve the ClientSecret from your original run of this function that created it. If you don't have it, you will need to go create a new client secret for your Microsoft Entra application. Please visit https://portal.azure.com and go to Home -> Microsoft Entra ID -> App Registrations -> (your app) '$AADAppDisplayName' -> Certificates and Secrets blade -> Client Secrets section." -ForegroundColor Yellow
    }
    Write-Host "*****`n"
    Write-Output (ConvertTo-Json $result)
}

  3. Create-ImmersiveReaderResource 함수를 실행하여 '<PARAMETER_VALUES>' 자리 표시자에 고유한 값을 적절하게 제공합니다.

    Create-ImmersiveReaderResource -SubscriptionName '<SUBSCRIPTION_NAME>' -ResourceName '<RESOURCE_NAME>' -ResourceSubdomain '<RESOURCE_SUBDOMAIN>' -ResourceSKU '<RESOURCE_SKU>' -ResourceLocation '<RESOURCE_LOCATION>' -ResourceGroupName '<RESOURCE_GROUP_NAME>' -ResourceGroupLocation '<RESOURCE_GROUP_LOCATION>' -AADAppDisplayName '<MICROSOFT_ENTRA_DISPLAY_NAME>' -AADAppIdentifierUri '<MICROSOFT_ENTRA_IDENTIFIER_URI>' -AADAppClientSecretExpiration '<MICROSOFT_ENTRA_CLIENT_SECRET_EXPIRATION>'

    전체 명령은 다음과 같습니다. 여기서는 명확성을 위해 각 매개 변수를 자체 줄에 배치하므로 전체 명령을 볼 수 있습니다. 이 명령을 그대로 복사하거나 사용하지 않습니다. 고유의 값으로 명령을 복사하여 사용합니다. 이 예제에는 .에 대한 더미 값이 있습니다 <PARAMETER_VALUES>. 이러한 값에 대한 고유한 이름을 생각해 내는 경우 사용자의 이름이 다를 수 있습니다.

    Create-ImmersiveReaderResource
    -SubscriptionName 'MyOrganizationSubscriptionName'
    -ResourceName 'MyOrganizationImmersiveReader'
    -ResourceSubdomain 'MyOrganizationImmersiveReader'
    -ResourceSKU 'S0'
    -ResourceLocation 'westus2'
    -ResourceGroupName 'MyResourceGroupName'
    -ResourceGroupLocation 'westus2'
    -AADAppDisplayName 'MyOrganizationImmersiveReaderAADApp'
    -AADAppIdentifierUri 'api://MyOrganizationImmersiveReaderAADApp'
    -AADAppClientSecretExpiration '2021-12-31'
    매개 변수 설명
    SubscriptionName 몰입형 리더 리소스에 사용할 Azure 구독의 이름입니다. 리소스를 만들기 위해서는 구독이 있어야 합니다.
    ResourceName 첫 번째 또는 마지막 문자가 아닌 한 - 영숫자여야 하며 포함-할 수 있습니다. 길이는 63자를 초과할 수 없습니다.
    ResourceSubdomain 사용자 지정 하위 도메인이 몰입형 리더 리소스에 필요합니다. 하위 도메인은 몰입형 리더 서비스를 호출하여 리더를 시작할 때 SDK에서 사용됩니다. 하위 도메인은 전역적으로 고유해야 합니다. 하위 기본 영숫자여야 하며 첫 번째 또는 마지막 문자가 아닌 한 - 포함-할 수 있습니다. 길이는 63자를 초과할 수 없습니다. 리소스가 이미 존재하는 경우 이 매개 변수는 선택 사항입니다.
    ResourceSKU 옵션: S0(표준 계층) 또는 S1(교육/비영리 조직)이 있습니다. 사용 가능한 각 SKU에 대해 자세히 알아보려면 Azure AI 서비스 가격 책정 페이지를 방문 하세요. 리소스가 이미 존재하는 경우 이 매개 변수는 선택 사항입니다.
    ResourceLocation 옵션: australiaeast, brazilsouth, canadacentral, centralindia, centralus, eastasia, eastus, eastus2, francecentral, germanywestcentral, japaneast, japanwest, jioindiawest, koreacentral, northcentralus, northeurope, norwayeast, southafricanorth, southcentralus, southeastasia, swedencentral, switzerlandnorth, switzerlandwest, uaenorth, uksouth, westcentralus, westeurope, westus, westus2, westus3 리소스가 이미 존재하는 경우 이 매개 변수는 선택 사항입니다.
    ResourceGroupName 리소스는 구독 내의 리소스 그룹에 만들어집니다. 기존 리소스 그룹의 이름을 제공합니다. 리소스 그룹이 아직 없으면 이 이름을 가진 새 리소스 그룹이 만들어집니다.
    ResourceGroupLocation 리소스 그룹이 없는 경우 그룹을 만들 위치를 제공해야 합니다. 위치 목록을 찾으려면 az account list-locations를 실행합니다. 반환된 결과의 name 속성(공백 없음)을 사용합니다. 리소스 그룹이 이미 있는 경우 이 매개 변수는 선택 사항입니다.
    AADAppDisplayName Microsoft Entra 애플리케이션 표시 이름입니다. 기존 Microsoft Entra 애플리케이션을 찾을 수 없는 경우 이 이름을 가진 새 애플리케이션이 만들어집니다. Microsoft Entra 애플리케이션이 이미 있는 경우 이 매개 변수는 선택 사항입니다.
    AADAppIdentifierUri Microsoft Entra 애플리케이션에 대한 URI입니다. 기존 Microsoft Entra 애플리케이션을 찾을 수 없는 경우 이 URI를 사용하는 새 애플리케이션이 만들어집니다. 예: api://MyOrganizationImmersiveReaderAADApp. 여기서는 확인된 do기본를 사용하는 Microsoft Entra 정책과의 호환성을 위해 기본 Microsoft Entra URI 스키마 접두사를 api:// 사용합니다.
    AADAppClientSecretExpiration Microsoft Entra Application Client Secret(암호)이 만료되는 날짜 또는 날짜/시간(예: '2020-12-31T11:59:59+00:00' 또는 '2020-12-31')입니다. 이 함수는 클라이언트 암호를 만듭니다.

    이 리소스를 만든 후 Microsoft Entra 애플리케이션 클라이언트 비밀을 관리하려면 Azure Portal을 방문하여 홈 -Microsoft Entra ID ->>앱 등록 -> (앱) [AADAppDisplayName] -인증서 및 비밀 섹션 ->>클라이언트 비밀 섹션으로 이동합니다.

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. 나중에 사용하기 위해 JSON 출력을 텍스트 파일로 복사합니다. 출력은 다음과 비슷합니다.

    {
  "TenantId": "...",
  "ClientId": "...",
  "ClientSecret": "...",
  "Subdomain": "..."
}

다음 단계

몰입형 리더 시작하는 방법