Crie um recurso Leitura Avançada e configuure a autenticação do Azure Ative Directory

Neste artigo, fornecemos um script que criará uma autenticação Leitura Avançada de recursos e configurará a autenticação do Azure Ative Directory (Azure AD). Cada vez que um recurso Leitura Avançada é criado, seja com este script ou no portal, também deve ser configurado com permissões Azure AD. Este guião vai ajudar-te com isso.

O script é projetado para criar e configurar todos os recursos necessários Leitura Avançada e Azure AD para todos vocês num só passo. No entanto, também pode configurar Azure AD autenticação para um recurso Leitura Avançada existente, se por acaso já tiver criado um no portal do Azure.

Para alguns clientes, pode ser necessário criar múltiplos recursos Leitura Avançada, para desenvolvimento vs. produção, ou talvez para várias regiões diferentes o seu serviço é implantado. Nesses casos, pode voltar e usar o script várias vezes para criar diferentes recursos Leitura Avançada e configurá-los com as permissões Azure AD.

O guião foi concebido para ser flexível. Primeiro procurará recursos Leitura Avançada e Azure AD existentes na sua subscrição, e criá-los-á apenas se não existirem. Se for a primeira vez que cria um recurso Leitura Avançada, o script fará tudo o que precisa. Se quiser usá-lo apenas para configurar Azure AD para um recurso Leitura Avançada existente que foi criado no portal, também o fará. Também pode ser usado para criar e configurar múltiplos recursos Leitura Avançada.

Configurar o ambiente PowerShell

  1. Comece por abrir o Azure Cloud Shell. Certifique-se de que Cloud Shell está definido para PowerShell no recuo superior esquerdo ou digitando pwsh.

  2. Copie e cole o seguinte corte de código na casca.

    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. Executar a função Create-ImmersiveReaderResource, fornecendo os espaços reservados '<PARAMETER_VALUES>' abaixo com os seus próprios valores, conforme apropriado.

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

    O comando completo será parecido com o seguinte. Aqui colocamos cada parâmetro na sua própria linha para a clareza, para que possa ver todo o comando. Não copie nem utilize este comando como está. Copie e use o comando acima com os seus próprios valores. Este exemplo tem valores falsos para o "<PARAMETER_VALUES>" acima. O seu será diferente, pois vai inventar os seus próprios nomes para estes valores.

    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'
    
    Parâmetro Comentários
    SubscriptionName Nome da subscrição Azure para usar para o seu recurso Leitura Avançada. Tem de ter uma subscrição para criar um recurso.
    ResourceName Deve ser alfanumérico, e pode conter '--, desde que o '-' não seja o primeiro ou último personagem. O comprimento não pode exceder 63 caracteres.
    ResourceSubdomain Um subdomínio personalizado é necessário para o seu recurso Leitura Avançada. O subdomínio é utilizado pelo SDK quando chama o serviço Leitura Avançada para lançar o Leitor. O subdomínio deve ser globalmente único. O subdomínio deve ser alfanumérico e pode conter '--, desde que o '-' não seja o primeiro ou último carácter. O comprimento não pode exceder 63 caracteres. Este parâmetro é opcional se o recurso já existir.
    ResourceSKU Opções: S0 (Nível padrão) ou S1 (Organizações de Educação/Sem Fins Lucrativos). Visite a nossa página de preços dos Serviços Cognitivos para saber mais sobre cada SKU disponível. Este parâmetro é opcional se o recurso já existir.
    ResourceLocation Opções: , , , centraluswesteuropenortheuropenorthcentralusnorwayeastkoreacentraljioindiawestjapanwestsouthafricanorthjapaneastgermanywestcentralfrancecentralsouthcentraluseastus2eastasiawestus2uaenorthwestusswedencentralswitzerlandnorthswitzerlandwestwestcentraluswestus3eastusuksouthcentralindiasoutheastasiacanadacentralbrazilsouthaustraliaeast Este parâmetro é opcional se o recurso já existir.
    ResourceGroupName Os recursos são criados em grupos de recursos dentro de subscrições. Forneça o nome de um grupo de recursos existente. Se o grupo de recursos já não existir, será criado um novo com este nome.
    ResourceGroupLocation Se o seu grupo de recursos não existir, precisa fornecer um local para criar o grupo. Para encontrar uma lista de locais, corra az account list-locations. Utilize a propriedade do nome (sem espaços) do resultado devolvido. Este parâmetro é opcional se o seu grupo de recursos já existir.
    Nome AADAppDisplay O nome de visualização da aplicação Azure Ative. Se não for encontrada uma aplicação de Azure AD existente, será criada uma nova com este nome. Este parâmetro é opcional se a aplicação Azure AD já existir.
    AADAppIdentifierUri O URI para a aplicação Azure AD. Se não for encontrada uma aplicação de Azure AD existente, será criada uma nova com este URI. Por exemplo, api://MyOrganizationImmersiveReaderAADApp. Aqui estamos a utilizar o prefixo do api:// regime URI Azure AD padrão por defeito para compatibilidade com a política Azure AD de utilização de domínios verificados.
    AADAppClientSecretExpiration A data ou data após a qual o seu Cliente Secreto (password) da aplicação AAD expirará (por exemplo, '2020-12-31T11:59:59+00:00' ou '2020-12-31'). Esta função criará um segredo de cliente para si. Para gerir Azure AD os segredos do cliente da aplicação depois de ter criado este recurso, visite https://portal.azure.com e vá ao Home -> Azure Ative Directory -> (a> sua app) [AADAppDisplayName] -> Certificados e Secrets blade -> Secção Segredos do Cliente (como mostra a imagem "Gerencie os seus segredos de aplicação Azure AD" abaixo).

    Gerencie os seus segredos de aplicação Azure AD

    Certificados e segredos do Portal Azure

  4. Copie a saída JSON num ficheiro de texto para utilização posterior. A saída deve parecer-se com a seguinte.

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

Passos seguintes