Een Insluitende lezer-resource maken en Azure Active Directory-verificatie configureren

  • Artikel

In dit artikel bieden we een script waarmee een Insluitende lezer-resource wordt gemaakt en azure Active Directory-verificatie (Azure AD) wordt geconfigureerd. Telkens wanneer een Insluitende lezer resource wordt gemaakt, of dit nu met dit script of in de portal is, moet deze ook worden geconfigureerd met Azure AD machtigingen.

Het script is ontworpen om in één stap alle benodigde Insluitende lezer en Azure AD resources voor u te maken en te configureren. U kunt echter ook gewoon Azure AD verificatie configureren voor een bestaande Insluitende lezer resource, bijvoorbeeld als u er al een hebt gemaakt in de Azure Portal.

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

Het script is ontworpen om flexibel te zijn. Eerst wordt gezocht naar bestaande Insluitende lezer en Azure AD resources in uw abonnement en worden deze alleen gemaakt als ze nog niet bestaan. Als het de eerste keer is dat u een Insluitende lezer-resource maakt, doet het script alles wat u nodig hebt. Als u deze alleen wilt gebruiken om Azure AD te configureren voor een bestaande Insluitende lezer resource die in de portal is gemaakt, gebeurt dat ook. Het kan ook worden gebruikt om meerdere Insluitende lezer resources te maken en te configureren.

Machtigingen

De vermelde eigenaar van uw Azure-abonnement beschikt over alle vereiste machtigingen om een Insluitende lezer resource te maken en Azure AD verificatie te configureren.

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

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

    Schermopname van de ingebouwde rolbeschrijving van inzender.

  • Toepassingsontwikkelaar. Er moet ten minste een rol van toepassingsontwikkelaar zijn gekoppeld aan Azure AD:

    {alt-text}

Zie ingebouwde rollen Azure AD voor meer informatie

PowerShell-omgeving instellen

  1. Open eerst de Azure Cloud Shell. Zorg ervoor dat Cloud Shell is ingesteld op PowerShell in de vervolgkeuzelijst linksboven of door te typenpwsh.

  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 Azure Active Directory 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 Azure Active Directory app"
        $clientId = az ad app create --display-name $AADAppDisplayName --identifier-uris $AADAppIdentifierUri --query "appId" -o tsv
        if (-not $clientId) {
            throw "Error: Failed to create Azure Active Directory application"
        }
        Write-Host "Azure Active Directory 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 Azure Active Directory application client secret"
        }
        Write-Host "Azure Active Directory application client secret created successfully."

        Write-Host "NOTE: To manage your Active Directory application client secrets after this Immersive Reader Resource has been created please visit https://portal.azure.com and go to Home -> Azure Active Directory -> 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 an Azure AD token
    $tenantId = az account show --query "tenantId" -o tsv

    # Collect the information needed to obtain an Azure AD 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 Azure Active Directory to fetch access tokens."
        Write-Host "This is the only time you will ever see the client secret for your Azure Active Directory 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 Azure Active Directory application. Please visit https://portal.azure.com and go to Home -> Azure Active Directory -> 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 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 '<AAD_APP_DISPLAY_NAME>' -AADAppIdentifierUri '<AAD_APP_IDENTIFIER_URI>' -AADAppClientSecretExpiration '<AAD_APP_CLIENT_SECRET_EXPIRATION>'

    De volledige opdracht ziet er ongeveer als volgt uit. Hier hebben we voor de duidelijkheid elke parameter op een eigen regel geplaatst, zodat u de hele opdracht kunt zien. Kopieer of gebruik deze opdracht niet als zodanig. Kopieer en gebruik de opdracht met uw eigen waarden. Dit voorbeeld bevat dummywaarden voor de '<PARAMETER_VALUES>'. De jouwe kan anders zijn, omdat je je eigen namen voor deze waarden bedenkt.

    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 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 mag '-' bevatten, zolang de '-' 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 globaal 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 (onderwijs-/non-profitorganisaties). Ga naar onze pagina met prijzen voor Cognitive Services voor meer informatie over elke beschikbare SKU. Deze parameter is optioneel als de resource al bestaat.
    ResourceLocation Opties: australiaeast, brazilsouth, , centralindiacanadacentral, centraluseastasia, eastus, eastus2, , francecentraljapaneastkoreacentraljapanwestnorthcentralusjioindiawestgermanywestcentral, northeurope, , norwayeastsouthafricanorth, swedencentralsoutheastasiaswitzerlandnorthwestcentralusuaenorthswitzerlandwestsouthcentraluswesteuropewestusuksouth, , , . westus3westus2 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 met deze naam gemaakt.
    ResourceGroupLocation Als uw resourcegroep niet bestaat, moet u een locatie opgeven waar u de groep wilt maken. Voer uit om een lijst met locaties te az account list-locationsvinden. Gebruik de eigenschap name (zonder spaties) van het geretourneerde resultaat. Deze parameter is optioneel als uw resourcegroep al bestaat.
    AADAppDisplayName De weergavenaam van de Azure Active Directory-toepassing. Als er geen bestaande Azure AD toepassing wordt gevonden, wordt er een nieuwe met deze naam gemaakt. Deze parameter is optioneel als de Azure AD toepassing al bestaat.
    AADAppIdentifierUri De URI voor de Azure AD-toepassing. Als er geen bestaande Azure AD toepassing wordt gevonden, wordt er een nieuwe met deze URI gemaakt. Bijvoorbeeld api://MyOrganizationImmersiveReaderAADApp. Hier gebruiken we het standaardvoorvoegsel api:// Azure AD URI-schema voor compatibiliteit met het Azure AD beleid voor het gebruik van geverifieerde domeinen.
    AADAppClientSecretExpiration De datum of datum/tijd waarna uw Azure AD toepassingsclientgeheim (wachtwoord) verloopt (bijvoorbeeld '2020-12-31T11:59:59+00:00' of '2020-12-31'). Met deze functie wordt een clientgeheim voor u gemaakt. Als u Azure AD clientgeheimen van toepassingen wilt beheren nadat u deze resource hebt gemaakt, gaat u naar https://portal.azure.com Start -> Azure Active Directory -> App-registraties -> (uw app) [AADAppDisplayName] -> Sectie Certificaten en geheimen -> Sectie Clientgeheimen (zoals wordt weergegeven in de schermafbeelding 'Uw Azure AD toepassingsgeheimen beheren').

    Uw Azure AD toepassingsgeheimen beheren

    Blade Certificaten en geheimen in Azure Portal

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

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

Volgende stappen