Quickstart: Configure uma aplicação multi-inquilino para o Microsoft Planetary Computer Pro

Neste início rápido, cria e configura uma aplicação Azure multitenant que pode aceder aos geocatálogos Microsoft Planetary Computer Pro do cliente. Como fornecedor de dados geoespaciais ou de serviços, este processo permite que a sua aplicação leia ou escreva dados a partir ou para os GeoCatálogos dos seus clientes.

Pré-requisitos

• Conta Azure com subscrição ativa (crie uma conta gratuita)
• Um dos seguintes papéis Microsoft Entra ID no seu locatário:
  • Administrador de aplicativos
  • Administrador de aplicativos na nuvem
  • Administrador Global
• Azure CLI instalado e configurado - instalar o Azure CLI
• Python 3.8 ou posterior (para exemplos de scripts)

Faça o download do código de exemplo

Este início rápido utiliza scripts de exemplo do repositório de aplicações parceiras Microsoft Planetary Computer Pro. Clone ou descarregue o repositório para a sua máquina 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 registo de aplicação multicliente

O primeiro passo é criar um registo de aplicação no seu tenant Azure configurado para acesso multiinquilino. Esta aplicação é a entidade que os clientes autorizam para aceder aos seus GeoCatálogos.

Compreender a configuração da aplicação

O registo de uma aplicação multi-inquilino requer uma configuração específica:

• Público de sessão de início: Definido para permitir iniciar sessão a partir de qualquer tenant Microsoft Entra
• URI de redirecionamento: URI onde os tokens são enviados após a autenticação
• Configuração do token: Ativar a emissão de ID e token de acesso
• Credenciais do cliente: Um segredo do cliente para autenticação apenas por aplicação

Crie a aplicação usando Azure CLI

1. Entre na CLI do Azure:

   az login
   

2. Crie o registo da aplicação multiinquilino:

   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 appId valor na saída é o ID da sua aplicação (cliente).

3. Crie uma entidade de serviço para a aplicação no seu tenant:

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

4. Crie um segredo para o cliente:

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

   Advertência

   Guarde o password valor de imediato — esta é a única vez em que é fornecido. Guarde-o de forma segura usando o Azure Key Vault ou outra solução de gestão de segredos.

5. Obtenha o seu ID de inquilino:

   az account show --query tenantId -o tsv
   

Usa o script de exemplo

Em alternativa, utilize o script de configuração fornecido para automatizar estes passos:

1. Navegue para o diretório provider-app:

   cd provider-app
   pip install -r requirements.txt
   

2. Crie um .env ficheiro com a 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. Executa o script de configuração:

   python setup_provider_app.py
   

O script cria o registo da aplicação e gera um customer_onboarding.json ficheiro contendo a informação que precisa de partilhar com os clientes.

Preparar os materiais de integração do cliente

Depois de criar a sua aplicação, prepare a informação de que os seus clientes precisam para autorizar a sua aplicação no seu tenant.

Informação obrigatória para os clientes

Fornecer aos clientes:

Gerar o URL de consentimento do administrador

Construa o URL do 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 este modelo aos clientes e instrua-os a substituir {customer-tenant-id} pelo seu próprio ID de inquilino.

Exemplo de documento de integração

O customer_onboarding.json ficheiro gerado pelo script de configuraçã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 aceder aos GeoCatálogos dos clientes

Assim que o seu cliente autoriza a sua aplicação cross-ten, pode autenticar e aceder aos seus recursos GeoCatalog.

Fluxo de autenticação

A sua aplicação autentica-se usando o fluxo de credenciais do cliente OAuth2:

Adquira um token de acesso

Use o fluxo de credenciais do cliente OAuth2 para adquirir um token para o âmbito do GeoCatalog. Para aplicações baseadas em Python, recomenda-se usar as bibliotecas MSAL para recuperar os tokens de acesso:

Exemplo em 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')}")

Faça pedidos de API

Com o token de acesso, faça pedidos à 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()

Teste sua configuração

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

1. Navegue até ao diretório da aplicação cliente:

   cd client-app
   pip install -r requirements.txt
   

2. Crie um .env ficheiro 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. Aquisição de token de teste:

   python test_oauth2_token.py
   

4. Teste o acesso ao GeoCatálogo:

   python test_geocatalog.py
   

Limpeza de recursos

Para remover o registo da candidatura quando já não for necessário:

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

Conteúdo relacionado

• Trabalhar com aplicações parceiras
• Autorizar aplicações de parceiros entre inquilinos
• Configurar autenticação de aplicações para o Microsoft Planetary Computer Pro