Een Insluitende lezer-resource maken en Microsoft Entra-verificatie configureren

  • Artikel

In dit artikel wordt uitgelegd hoe u een Insluitende lezer resource maakt met behulp van het opgegeven script. Dit script configureert ook Microsoft Entra-verificatie. Telkens wanneer een Insluitende lezer resource wordt gemaakt, ongeacht of dit script of in de portal wordt gebruikt, moet deze worden geconfigureerd met Microsoft Entra-machtigingen.

Het script maakt en configureert alle benodigde Insluitende lezer en Microsoft Entra-resources voor u. U kunt echter ook Microsoft Entra-verificatie configureren voor een bestaande Insluitende lezer-resource, als u er al een hebt gemaakt in Azure Portal. Het script zoekt eerst naar bestaande Insluitende lezer- en Microsoft Entra-resources in uw abonnement en maakt ze alleen als ze nog niet bestaan.

Voor sommige klanten kan het nodig zijn om meerdere Insluitende lezer resources te maken, voor ontwikkeling versus productie, of misschien voor verschillende regio's waar uw service wordt geïmplementeerd. In dergelijke gevallen kunt u het script meerdere keren gebruiken om verschillende Insluitende lezer resources te maken en deze te configureren met Microsoft Entra-machtigingen.

Bevoegdheden

De vermelde eigenaar van uw Azure-abonnement heeft alle vereiste machtigingen om een Insluitende lezer resource te maken en Microsoft Entra-verificatie te configureren.

Als u geen eigenaar bent, zijn de volgende bereikspecifieke machtigingen vereist:

  • Inzender. U moet ten minste de rol Inzender hebben die is gekoppeld aan het Azure-abonnement:

    Screenshot of contributor built-in role description.

  • Toepassingsontwikkelaar. U moet ten minste een rol van toepassingsontwikkelaar hebben die is gekoppeld aan de Microsoft Entra-id:

    Screenshot of the developer built-in role description.

Zie Ingebouwde rollen in Microsoft Entra voor meer informatie.

PowerShell-resources instellen

  1. Begin met het openen van Azure Cloud Shell. Zorg ervoor dat Cloud Shell is ingesteld op PowerShell in de vervolgkeuzelijst linksboven of door te typen pwsh.

  2. Kopieer en plak het volgende codefragment in de shell.

    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. Voer de functie Create-ImmersiveReaderResourceuit en geef waar nodig de tijdelijke aanduidingen '<PARAMETER_VALUES>' op met uw eigen waarden.

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

    De volledige opdracht ziet er ongeveer als volgt uit. Hier plaatsen we elke parameter op een eigen regel voor duidelijkheid, zodat u de hele opdracht kunt zien. Kopieer of gebruik deze opdracht niet als zodanig. Kopieer en gebruik de opdracht met uw eigen waarden. In dit voorbeeld zijn dummywaarden voor de <PARAMETER_VALUES>. Uw waarden kunnen anders zijn, omdat u uw eigen namen voor deze waarden hebt.

    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 Opmerkingen
    SubscriptionName De naam van het Azure-abonnement dat moet worden gebruikt voor uw Insluitende lezer-resource. U moet een abonnement hebben om een resource te kunnen maken.
    ResourceName Moet alfanumeriek zijn en kan bevatten -, zolang het niet het - eerste of laatste teken is. De lengte mag niet langer zijn dan 63 tekens.
    ResourceSubdomain Er is een aangepast subdomein nodig voor uw Insluitende lezer resource. Het subdomein wordt door de SDK gebruikt bij het aanroepen van de Insluitende lezer-service om de lezer te starten. Het subdomein moet wereldwijd uniek zijn. Het subdomein moet alfanumeriek zijn en kan bevatten -, zolang het niet het - eerste of laatste teken is. De lengte mag niet langer zijn dan 63 tekens. Deze parameter is optioneel als de resource al bestaat.
    ResourceSKU Opties: S0 (Standard-laag) of S1 (Education/Nonprofit-organisaties). Ga naar onze pagina met prijzen voor Azure AI-services voor meer informatie over elke beschikbare SKU. Deze parameter is optioneel als de resource al bestaat.
    ResourceLocation Opties: australiaeast, brazilsouth, canadacentral, centralindia, , centralus, eastasia, eastus2francecentraleastus, germanywestcentral, japaneast, switzerlandnorthuaenorthjioindiawestsouthcentralusjapanwestkoreacentralnorthcentralusnorwayeastsouthafricanorthswitzerlandwestsoutheastasiauksouthnortheuropeswedencentral, westcentralus, westeurope, , , westuswestus2westus3 Deze parameter is optioneel als de resource al bestaat.
    ResourceGroupName Resources worden gemaakt in resourcegroepen binnen abonnementen. Geef de naam van een bestaande resourcegroep op. Als de resourcegroep nog niet bestaat, wordt er een nieuwe gemaakt met deze naam.
    ResourceGroupLocation Als uw resourcegroep niet bestaat, moet u een locatie opgeven waar de groep moet worden gemaakt. Voer uit az account list-locationsom een lijst met locaties te vinden. Gebruik de naameigenschap (zonder spaties) van het geretourneerde resultaat. Deze parameter is optioneel als uw resourcegroep al bestaat.
    AADAppDisplayName De weergavenaam van de Microsoft Entra-toepassing. Als er geen bestaande Microsoft Entra-toepassing wordt gevonden, wordt er een nieuwe met deze naam gemaakt. Deze parameter is optioneel als de Microsoft Entra-toepassing al bestaat.
    AADAppIdentifierUri De URI voor de Microsoft Entra-toepassing. Als er geen bestaande Microsoft Entra-toepassing wordt gevonden, wordt er een nieuwe met deze URI gemaakt. Bijvoorbeeld api://MyOrganizationImmersiveReaderAADApp. Hier gebruiken we het standaardvoorvoegsel van api:// het Microsoft Entra URI-schema voor compatibiliteit met het Microsoft Entra-beleid voor het gebruik van geverifieerde domeinen.
    AADAppClientSecretExpiration De datum of datum/tijd waarna uw Microsoft Entra Application Client Secret (wachtwoord) verloopt (bijvoorbeeld '2020-12-31T11:59:59+00:00' of '2020-12-31'). Met deze functie maakt u een clientgeheim.

    Als u de clientgeheimen van uw Microsoft Entra-toepassing wilt beheren nadat u deze resource hebt gemaakt, gaat u naar Azure Portal en gaat u naar Home ->Microsoft Entra ID ->App-registraties -> (uw app) [AADAppDisplayName] -> Sectie Certificaten en geheimen ->Clientgeheimen.

    Screenshot of the Azure portal Certificates and Secrets pane.

  4. Kopieer de JSON-uitvoer naar een tekstbestand voor later gebruik. De uitvoer moet er als volgt uitzien.

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

Volgende stap

De Insluitende lezer starten