Schnellstart: Konfigurieren einer mandantenübergreifenden Anwendung für Microsoft Planetary Computer Pro

In dieser Schnellstartanleitung erstellen und konfigurieren Sie eine mehrinstanzenfähige Azure-Anwendung, die auf kundenseitige Microsoft Planetary Computer Pro GeoCatalogs zugreifen kann. Als Geodaten- oder Dienstanbieter ermöglicht dieser Prozess Ihrer Anwendung, Daten aus den GeoKatalogen Ihrer Kunden zu lesen oder in diese zu schreiben.

Voraussetzungen

• Azure Konto mit einem aktiven Abonnement (erstellen Sie ein free-Konto
• Eine der folgenden Microsoft Entra-ID-Rollen in Ihrem Mandanten:
  • Anwendungsadministrator
  • Cloudanwendungsadministrator
  • Globaler Administrator
• Azure CLI installiert und konfiguriert – Installieren der Azure CLI
• Python 3.8 oder höher (für Beispielskripts)

Herunterladen des Beispielcodes

In dieser Schnellstartanleitung werden Beispielskripts aus dem Microsoft Planetary Computer Pro-Partneranwendungs-Repository verwendet. Klonen sie, oder laden Sie das Repository auf Ihren lokalen Computer herunter:

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

Das Repository enthält drei Verzeichnisse:

Erstellen einer Mehrinstanzenanwendungsregistrierung

Der erste Schritt besteht darin, eine Anwendungsregistrierung in Ihrem Azure-Mandanten zu erstellen, die für den mehrinstanzenfähigen Zugriff konfiguriert ist. Diese Anwendung ist die Entität, die Kunden für den Zugriff auf ihre GeoCatalogs autorisieren.

Grundlegendes zur Anwendungskonfiguration

Für eine Mehrinstanzenanwendungsregistrierung ist eine bestimmte Konfiguration erforderlich:

• Anmeldepublikum: Einstellen auf AzureADMultipleOrgs, um die Anmeldung von einem beliebigen Microsoft Entra-Mandanten zuzulassen
• Umleitungs-URI: URI, an den Token nach der Authentifizierung gesendet werden
• Tokenkonfiguration: Aktivieren der ID- und Zugriffstokenausstellung
• Clientanmeldeinformationen: Ein geheimer Clientschlüssel für die Nur-App-Authentifizierung

Erstellen der Anwendung mit Azure CLI

1. Anmelden bei der Azure CLI an:

   az login
   

2. Erstellen Sie die Mehrinstanzenanwendungsregistrierung:

   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
   

   Hinweis

   Der appId Wert in der Ausgabe ist Ihre Anwendungs-ID (Client-ID).

3. Erstellen Sie einen Dienstprinzipal für die Anwendung in Ihrem Mandanten:

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

4. Erstellen Sie ein Client Secret:

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

   Warnung

   Speichern Sie den password Wert sofort – dies ist das einzige Mal, wenn er bereitgestellt wird. Speichern Sie sie sicher mithilfe von Azure Key Vault oder einer anderen Lösung für die Verwaltung geheimer Schlüssel.

5. Abrufen Ihrer Mandanten-ID:

   az account show --query tenantId -o tsv
   

Verwenden des Beispielskripts

Verwenden Sie alternativ das bereitgestellte Setupskript, um die folgenden Schritte zu automatisieren:

1. Navigieren Sie zum Anbieter-App-Verzeichnis:

   cd provider-app
   pip install -r requirements.txt
   

2. Erstellen Sie eine .env Datei mit Ihrer Konfiguration:

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

3. Führen Sie das Setupskript aus:

   python setup_provider_app.py
   

Das Skript erstellt die Anwendungsregistrierung und gibt eine customer_onboarding.json Datei mit den Informationen aus, die Sie für Kunden freigeben müssen.

Vorbereiten von Onboardingmaterialien für Kunden

Bereiten Sie nach dem Erstellen Der Anwendung die Informationen vor, die Ihre Kunden benötigen, um Ihre Anwendung in ihrem Mandanten zu autorisieren.

Erforderliche Informationen für Kunden

Bieten Sie Kunden Folgendes:

Generiere die Administrator-Zustimmungs-URL

Erstellen Sie die Administratorzustimmungs-URL mithilfe dieser Vorlage:

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

Stellen Sie Kunden diese Vorlage bereit und weisen Sie sie an, {customer-tenant-id} durch ihre eigene Mandanten-ID zu ersetzen.

Beispiel für ein Onboarding-Dokument

Die customer_onboarding.json vom Setupskript generierte Datei enthält:

{
  "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"
  }
}

Authentifizieren und Zugreifen auf GeoCatalogs für Kunden

Nachdem Ihr Kunde die mandantenübergreifende Anwendung autorisiert hat, können Sie sich authentifizieren und auf seine GeoCatalog-Ressourcen zugreifen.

Authentifizierungsfluss

Ihre Anwendung authentifiziert sich mithilfe des OAuth2-Clientanmeldeinformationsflusses:

Ein Zugriffstoken abrufen

Verwenden Sie den OAuth2-Clientanmeldeinformationsfluss, um ein Token für den GeoCatalog-Bereich abzurufen. Für Python-basierte Anwendung wird empfohlen, die MSAL-Bibliotheken zum Abrufen der Zugriffstoken zu verwenden:

Python-Beispiel mit 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')}")

API-Anforderungen stellen

Stellen Sie mit dem Zugriffstoken Anforderungen an die GeoCatalog-API des Kunden vor:

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()

Testen der Konfiguration

Sie können die Testskripts im client-app/ Verzeichnis verwenden, um Ihre Konfiguration zu überprüfen:

1. Navigieren Sie zum Client-App-Verzeichnis:

   cd client-app
   pip install -r requirements.txt
   

2. Erstellen Sie eine .env Datei mit der Konfiguration des Kunden:

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

3. Tokenakquisition testen:

   python test_oauth2_token.py
   

4. GeoCatalog-Zugriff testen:

   python test_geocatalog.py
   

Bereinigen von Ressourcen

So entfernen Sie die Anwendungsregistrierung, wenn sie nicht mehr benötigt wird:

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

Verwandte Inhalte

• Arbeiten mit Partneranwendungen
• Autorisieren von mandantenübergreifenden Partneranwendungen
• Konfigurieren der Anwendungsauthentifizierung für Microsoft Planetary Computer Pro