Início Rápido: Configurar um aplicativo entre os locatários para o Computador Planetário Pro da Microsoft

Neste início rápido, você criará e configurará um aplicativo multilocatário do Azure que possa acessar os GeoCatalogs do Computador Planetário Pro da Microsoft do cliente. Como um provedor de serviços ou dados geoespaciais, esse processo permite que seu aplicativo leia ou escreva dados de ou para os GeoCatalogs de seus clientes.

Pré-requisitos

• Conta do Azure com uma assinatura ativa (criar uma conta gratuita)
• Uma das seguintes funções do Microsoft Entra ID em seu locatário:
  • Administrador de aplicativos
  • Administrador de Aplicativos na Nuvem
  • Administrador global
• CLI do Azure instalada e configurada – instalar a CLI do Azure
• Python 3.8 ou posterior (para scripts de exemplo)

Baixar o código de exemplo

Este início rápido usa scripts de exemplo do repositório de aplicativos do parceiro Microsoft Planetary Computer Pro. Clone ou baixe o repositório em seu computador local:

git clone https://github.com/Azure/microsoft-planetary-computer-pro.git
cd tools/partner-app-integration

O repositório contém três diretórios:

Criar um registro de aplicativo multilocatário

A primeira etapa é criar um registro de aplicativo em seu locatário do Azure configurado para acesso multilocatário. Este aplicativo é a entidade que os clientes autorizam a acessar seus GeoCatalogs.

Entender a configuração do aplicativo

Um registro de aplicativo multilocatário requer uma configuração específica:

• Público-alvo de entrada: definido como AzureADMultipleOrgs para permitir a entrada direto de qualquer locatário do Microsoft Entra
• URI de redirecionamento: URI para onde os tokens são enviados após a autenticação
• Configuração de token: habilitar a ID e a emissão de token de acesso
• Credenciais do cliente: um segredo do cliente para autenticação somente de aplicativo

Criar o aplicativo usando a CLI do Azure

1. Entre na CLI do Azure:

   az login
   

2. Criar o registro de aplicativo multilocatário:

   az ad app create \
     --display-name "My Geospatial Provider App" \
     --sign-in-audience AzureADMultipleOrgs \
     --web-redirect-uris "https://localhost:8080/callback" \
     --enable-id-token-issuance true \
     --enable-access-token-issuance true
   

   Observação

   O valor appId na saída é o ID de Aplicativo (cliente).

3. Crie um principal de serviço para o aplicativo em seu tenant:

   az ad sp create --id <your-app-id>
   

4. Criar um segredo do cliente:

   az ad app credential reset \
     --id <your-app-id> \
     --append \
     --years 1
   

   Aviso

   Salve o password valor imediatamente , esta é a única vez que ele é fornecido. Armazene-o com segurança usando o Azure Key Vault ou outra solução de gerenciamento de segredos.

5. Obtenha sua ID de locatário:

   az account show --query tenantId -o tsv
   

Use o script de exemplo

Como alternativa, use o script de instalação fornecido para automatizar estas etapas:

1. Navegue até o diretório provedor-aplicativo:

   cd provider-app
   pip install -r requirements.txt
   

2. Crie um .env arquivo com sua configuração:

   AZURE_TENANT_ID=<your-tenant-id>
   PROVIDER_APP_NAME=my-geospatial-provider-app
   PROVIDER_APP_REDIRECT_URI=https://localhost:8080/callback
   

3. Execute o script de instalação:

   python setup_provider_app.py
   

O script cria o registro do aplicativo e gera um customer_onboarding.json arquivo que contém as informações necessárias para compartilhar com os clientes.

Preparar materiais de integração do cliente

Depois de criar seu aplicativo, prepare as informações de que seus clientes precisam para autorizar seu aplicativo em seu locatário.

Informações necessárias para os clientes

Forneça aos clientes:

Gerar a URL de consentimento do administrador

Construa a URL de consentimento do administrador usando este modelo:

https://login.microsoftonline.com/{customer-tenant-id}/adminconsent?client_id={your-app-id}&redirect_uri={your-redirect-uri}

Forneça aos clientes esse modelo e instrua-os a substituir {customer-tenant-id} por sua própria ID de locatário.

Exemplo de documento de integração

O customer_onboarding.json arquivo gerado pelo script de instalação contém:

{
  "provider_app_name": "my-geospatial-provider-app",
  "application_id": "abcd1234-ef56-7890-abcd-1234567890ab",
  "admin_consent_url_template": "https://login.microsoftonline.com/{customer-tenant-id}/adminconsent?client_id=abcd1234-ef56-7890-abcd-1234567890ab&redirect_uri=https://localhost:8080/callback",
  "instructions": {
    "step_1": "Customer admin navigates to admin consent URL",
    "step_2": "Admin grants consent for requested permissions",
    "step_3": "Customer runs customer-app registration script",
    "step_4": "Customer assigns GeoCatalog Administrator role to the service principal"
  }
}

Autenticar e acessar GeoCatalogs do cliente

Depois que o cliente autorizar o aplicativo entre os locatários, você poderá autenticar e acessar os recursos do GeoCatalog.

Fluxo de autenticação

Seu aplicativo é autenticado usando o fluxo de credenciais do cliente OAuth2:

Adquirir um token de acesso

Use o fluxo de credenciais do cliente OAuth2 para adquirir um token para o escopo do GeoCatalog. Para o aplicativo baseado em Python, é recomendável usar as bibliotecas MSAL para recuperar os tokens de acesso:

Exemplo de Python usando MSAL:

import msal

def get_access_token_msal(tenant_id, client_id, client_secret):
    """Acquire access token using MSAL."""
    app = msal.ConfidentialClientApplication(
        client_id=client_id,
        client_credential=client_secret,
        authority=f"https://login.microsoftonline.com/{tenant_id}"
    )
    
    result = app.acquire_token_for_client(
        scopes=["https://geocatalog.spatio.azure.com/.default"]
    )
    
    if "access_token" in result:
        return result["access_token"]
    else:
        raise Exception(f"Token acquisition failed: {result.get('error_description')}")

Fazer solicitações de API

Com o token de acesso, faça solicitações para a API geocatalog do cliente:

import requests

def list_collections(geocatalog_url, access_token, collection_id):
    """Get a specific collection from the GeoCatalog."""
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    }
    
    response = requests.get(
        f"{geocatalog_url}/stac/collections/{collection_id}",
        headers=headers
    )
    
    response.raise_for_status()
    return response.json()

Testar sua configuração

Você pode usar os scripts de teste no client-app/ diretório para validar sua configuração:

1. Navegue até o diretório do aplicativo cliente:

   cd client-app
   pip install -r requirements.txt
   

2. Crie um .env arquivo com a configuração do cliente:

   AZURE_CLIENT_ID=<your-app-id>
   AZURE_TENANT_ID=<customer-tenant-id>
   AZURE_CLIENT_SECRET=<your-client-secret>
   GEOCATALOG_URL=<customer-geocatalog-url>
   

3. Testar a aquisição de tokens:

   python test_oauth2_token.py
   

4. Testar o acesso do GeoCatalog:

   python test_geocatalog.py
   

Limpar os recursos

Para remover o registro do aplicativo quando ele não for mais necessário:

# Delete the application registration
az ad app delete --id <your-app-id>

Conteúdo relacionado

• Trabalhando com aplicativos parceiros
• Autorizar os aplicativos de parceiro entre os locatários
• Configurar a autenticação de aplicativo para o Microsoft Planetary Computer Pro