Erstellen einer Immersive Reader-Ressource und Konfigurieren der Microsoft Entra-Authentifizierung

  • Artikel

In diesem Artikel wird erläutert, wie Sie mithilfe des bereitgestellten Skripts eine Immersive Reader-Ressource erstellen. Dieses Skript konfiguriert auch die Microsoft Entra-Authentifizierung. Jedes Mal, wenn eine Immersive Reader-Ressource mit diesem Skript oder im Portal erstellt wird, muss sie mit Microsoft Entra-Berechtigungen konfiguriert werden.

Das Skript erstellt und konfiguriert alle notwendige Immersive Reader- und Microsoft Entra-Ressourcen für Sie in einem Schritt. Sie können jedoch auch die Microsoft Entra-Authentifizierung für eine vorhandene Immersive Reader-Ressource konfigurieren, wenn Sie bereits eine im Azure-Portal erstellt haben. Zunächst sucht das Skript nach vorhandenen Immersive Reader- und Microsoft Entra-Ressourcen in Ihrem Abonnement. Diese werden lediglich erstellt, wenn sie nicht bereits vorhanden sind.

Einige Kunden müssen möglicherweise mehrere Plastischer Reader-Ressourcen für Entwicklung und Produktion erstellen, oder vielleicht für verschiedene Regionen, in denen ihr Dienst bereitgestellt wird. In diesen Fällen können Sie das Skript mehrmals verwenden, um unterschiedliche Immersive Reader-Ressourcen zu erstellen und diese mit den Microsoft Entra-Berechtigungen zu konfigurieren.

Berechtigungen

Der oder die aufgeführte Besitzer*in Ihres Azure-Abonnements verfügt über alle erforderlichen Berechtigungen, um eine Immersive Reader-Ressource zu erstellen und die Microsoft Entra-Authentifizierung zu konfigurieren.

Wenn Sie kein Besitzer sind, sind die folgenden bereichsspezifischen Berechtigungen erforderlich:

  • Mitwirkender: Sie benötigen mindestens die Rolle „Mitwirkender“, die dem Azure-Abonnement zugeordnet ist:

    Screenshot of contributor built-in role description.

  • Anwendungsentwickler Sie benötigen mindestens die Rolle „Anwendungsentwickler“ in Microsoft Entra ID:

    Screenshot of the developer built-in role description.

Weitere Informationen finden Sie unter Integrierte Rollen in Microsoft Entra.

Einrichten von PowerShell-Ressourcen

  1. Öffnen Sie als Erstes die Azure Cloud Shell. Stellen Sie in der Dropdownliste oben links oder durch Eingabe von pwsh sicher, dass Cloud Shell auf PowerShell festgelegt ist.

  2. Kopieren Sie den folgenden Codeausschnitt, und fügen Sie ihn in die Shell ein.

    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. Führen Sie die Funktion „Create-ImmersiveReaderResource“ aus, und stellen Sie den „<PARAMETER_VALUES>“-Platzhalter mit Ihren eigenen Werten bereit.

    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>'

    Der vollständige Befehl sieht in etwa wie folgt aus. Hier wurde jeder Parameter aus Gründen der Übersichtlichkeit in eine eigene Zeile eingefügt, damit Sie den gesamten Befehl sehen können. Kopieren oder verwenden Sie diesen Befehl nicht unverändert. Kopieren Sie den Befehl mit Ihren eigenen Werten, und verwenden Sie ihn erst dann. Dieses Beispiel enthält Pseudowerte für <PARAMETER_VALUES>. Ihre Werte unterscheiden sich eventuell, da Sie eigene Namen für diese Werte verwenden.

    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'
    Parameter Kommentare
    SubscriptionName Der Name des Azure-Abonnements, das für Ihre Plastischer Reader-Ressource verwendet werden soll. Sie müssen über ein Abonnement verfügen, um eine Ressource zu erstellen.
    Ressourcenname Muss alphanumerisch sein und darf - enthalten, solange - nicht das erste oder letzte Zeichen ist. Die Länge darf nicht 63 Zeichen überschreiten.
    ResourceSubdomain Eine benutzerdefinierte Unterdomäne ist für Ihre Plastischer Reader-Ressource erforderlich. Die Unterdomäne wird vom SDK verwendet, wenn der Plastischer Reader-Dienst aufgerufen wird, um den Reader zu starten. Die Unterdomäne muss global eindeutig sein. Die Unterdomäne muss alphanumerisch sein und darf - enthalten, solange - nicht das erste oder letzte Zeichen ist. Die Länge darf nicht 63 Zeichen überschreiten. Dieser Parameter ist optional, wenn die Ressource bereits vorhanden ist.
    ResourceSKU Optionen: S0 (Standardebene) oder S1 (Bildungsorganisationen bzw. Non-Profit-Organisationen). Besuchen Sie unsere Seite mit den Preisen für Azure KI Services, um mehr über jede verfügbare SKU zu erfahren. Dieser Parameter ist optional, wenn die Ressource bereits vorhanden ist.
    ResourceLocation Optionen: 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. Dieser Parameter ist optional, wenn die Ressource bereits vorhanden ist.
    ResourceGroupName Ressourcen werden in Ressourcengruppen in Abonnements erstellt. Geben Sie den Namen einer vorhandenen Ressourcengruppe an. Wenn die Ressourcengruppe nicht bereits vorhanden ist, wird eine neue mit diesem Namen erstellt.
    ResourceGroupLocation Wenn die Ressourcengruppe nicht vorhanden ist, müssen Sie einen Speicherort angeben, an dem die Gruppe erstellt werden soll. Verwenden Sie az account list-locations zum Abrufen einer Speicherortliste. Verwenden Sie die Eigenschaft Name (ohne Leerzeichen) des zurückgegebenen Ergebnisses. Dieser Parameter ist optional, wenn die Ressource bereits vorhanden ist.
    AADAppDisplayName Dabei handelt es sich um den Anzeigenamen der Microsoft Entra-Anwendung. Wenn keine vorhandene Microsoft Entra-Anwendung gefunden wird, wird eine neue mit diesem Namen erstellt. Dieser Parameter ist optional, wenn die Microsoft Entra-Anwendung bereits vorhanden ist.
    AADAppIdentifierUri Dabei handelt es sich um den URI für die Microsoft Entra-Anwendung. Wenn keine vorhandene Microsoft Entra-Anwendung gefunden wird, wird eine neue mit diesem URI erstellt. Beispiel: api://MyOrganizationImmersiveReaderAADApp. Hier wird das Standard-URI-Schemapräfix api:// von Microsoft Entra verwendet, um die Kompatibilität mit der Microsoft Entra-Richtlinie zur Verwendung verifizierter Domänen zu gewährleisten.
    AADAppClientSecretExpiration Die Datentypen „date“ oder „datetime“, nach denen der geheime Clientschlüssel der Microsoft Entra-Anwendung (Kennwort) abläuft (z. B. „2020-12-31T11:59:59+00:00“ oder „2020-12-31“). Diese Funktion erstellt einen geheimen Clientschlüssel für Sie.

    Informationen zur Verwaltung der geheimen Clientschlüssel Ihrer Microsoft Entra-Anwendungen nach der Erstellung dieser Ressource finden Sie im Azure-Portal. Navigieren Sie dort über Startseite ->Microsoft Entra ID ->App-Registrierungen“ -> (Ihre App) [AADAppDisplayName] zu den Abschnitten ->Zertifikate und Geheimnisse ->Geheime Clientschlüssel.

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. Kopieren Sie die JSON-Ausgabe zur späteren Verwendung in eine Textdatei. Die Ausgabe sollte wie im folgenden Beispiel aussehen.

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

Nächster Schritt

Starten des plastischen Readers