Verwenden von Microsoft Entra ID und nativen PostgreSQL-Rollen für die Authentifizierung mit Azure Cosmos DB for PostgreSQL

  • Artikel

GILT FÜR: Azure Cosmos DB for PostgreSQL (unterstützt von der Citus-Datenbankerweiterung auf PostgreSQL)

In diesem Artikel konfigurieren Sie Authentifizierungsmethoden für Azure Cosmos DB for PostgreSQL. Sie verwalten Microsoft Entra ID Admin-Benutzer*innen und native PostgreSQL-Rollen für die Authentifizierung mit Azure Cosmos DB for PostgreSQL. Sie lernen auch, wie Sie ein Microsoft Entra ID-Token mit Azure Cosmos DB for PostgreSQL verwenden.

Ein Azure Cosmos DB for PostgreSQL-Cluster wird mit einer integrierten nativen PostgreSQL-Rolle namens „citus“ erstellt. Sie können nach Abschluss der Clusterbereitstellung weitere native PostgreSQL-Rollen hinzufügen.

Sie können auch die Microsoft Entra ID-Authentifizierung (früher Azure Active Directory) für Azure Cosmos DB for PostgreSQL konfigurieren. Sie können die Microsoft Entra ID-Authentifizierung zusätzlich oder anstelle der nativen PostgreSQL-Authentifizierung in Ihrem Cluster aktivieren. Sie können die für den Cluster aktivierten Authentifizierungsmethoden jederzeit ändern, nachdem der Cluster bereitgestellt wurde. Wenn die Microsoft Entra ID-Authentifizierung aktiviert ist, können Sie mehrere Microsoft Entra ID-Benutzer*innen zu einem Azure Cosmos DB for PostgreSQL-Cluster hinzufügen und jeden von ihnen zu Administrator*innen machen. Microsoft Entra-Benutzer*innen können Benutzer*innen oder Dienstprinzipale sein.

Auswählen einer Authentifizierungsmethode

Sie müssen das Azure-Portal verwenden, um Authentifizierungsmethoden für einen Azure Cosmos DB for PostgreSQL-Cluster zu konfigurieren.

Führen Sie die folgenden Schritte auf Ihrem Azure Cosmos DB for PostgreSQL-Cluster durch, um die Microsoft Entra ID-Authentifizierung und die native PostgreSQL-Authentifizierung zu aktivieren oder zu deaktivieren.

  1. Wählen Sie auf der Clusterseite unter der Überschrift Clusterverwaltung die Option Authentifizierung aus, um die Authentifizierungsverwaltungsoptionen zu öffnen.
  2. Wählen Sie im Abschnitt Authentifizierungsmethoden je nach Ihren Anforderungen nur die PostgreSQL-Authentifizierung, die Microsoft Entra ID-Authentifizierung oder die PostgreSQL- und Microsoft Entra ID-Authentifizierung als Authentifizierungsmethode.

Fahren Sie anschließend mit der Konfiguration der Microsoft Entra ID-Authentifizierung oder dem Hinzufügen nativer PostgreSQL-Rollen auf der gleichen Seite Authentifizierung fort.

Konfigurieren der Microsoft Entra-Authentifizierung

Voraussetzungen

Benutzer*innen müssen die Berechtigung haben, sich bei Azure Cosmos DB for PostgreSQL im Microsoft Entra ID-Mandanten anzumelden. Diese Schritte sollten einmal für den Microsoft Entra ID-Mandanten durchgeführt werden, der für die Authentifizierung auf Azure Cosmos DB for PostgreSQL-Clustern verwendet werden soll.

Wichtig

Für die Änderung sind Administratorrechte für Microsoft Entra ID-Mandanten erforderlich. Weitere Informationen finden Sie im Leitfaden für die Problembehandlung von Berechtigungen.

  1. Suchen Sie im Azure-Portal nach „Microsoft Entra ID“.
  2. Öffnen Sie den Dienst „Microsoft Entra ID“.
  3. Suchen Sie auf der Seite Übersicht des Microsoft Entra ID-Diensts im Abschnitt Übersicht nach der Anwendungs-ID „b4fa09d8-5da5-4352-83d9-05c2a44cf431“.
  4. Wählen Sie in den Suchergebnissen die Unternehmensanwendung „Azure Cosmos DB for PostgreSQL AAD Authentication“ aus.
  5. Wählen Sie in der Azure Cosmos DB for PostgreSQL AAD Authentication-Unternehmensanwendung die Seite Eigenschaften aus.
  6. Legen Sie die Option Für die Benutzeranmeldung freigegeben? auf Ja fest.

Hinweis

Für die Bearbeitung der Eigenschaften von Unternehmensanwendungen, wie z. B. „Anmeldung für Benutzer aktiviert“, sind die Berechtigungen der Rollen Globaler Administrator, Cloud-Anwendungsadministrator oder Anwendungsadministrator erforderlich. Siehe die Liste der integrierten Microsoft Entra-Rollen.

Hinzufügen von Microsoft Entra ID-Administrator*innen zum Azure Cosmos DB for PostgreSQL-Cluster

Führen Sie die folgenden Schritte auf der Seite Authentifizierung aus, um Microsoft Entra ID-Rollen im Cluster hinzuzufügen oder zu entfernen:

  1. Wählen Sie im Abschnitt Microsoft Entra ID-Authentifizierung die Option Microsoft Entra ID-Administrator*innen hinzufügen aus.
  2. Wählen Sie im Bereich Microsoft Entra ID-Administrator*innen auswählen eine oder mehrere gültige Microsoft Entra-Benutzer*innen oder Unternehmensanwendung im aktuellen AD-Mandanten aus, um sie zu Microsoft Entra-Administrator*innen in Ihrem Azure Cosmos DB for PostgreSQL-Cluster zu machen.
  3. Bestätigen Sie Ihre Auswahl mit Auswählen.
  4. Wählen Sie auf der Seite Authentifizierung auf der Symbolleiste Speichern aus, um Änderungen zu speichern oder mit dem Hinzufügen nativer PostgreSQL-Rollen fortzufahren.

Konfigurieren der nativen PostgreSQL-Authentifizierung

Führen Sie die folgenden Schritte auf der Seite Authentifizierung aus, um Postgres-Rollen im Cluster hinzuzufügen:

  1. Wählen Sie im Abschnitt PostgreSQL-Authentifizierung die Option PostgreSQL-Rolle hinzufügen aus.
  2. Geben Sie den Rollennamen und das Kennwort ein. Wählen Sie Speichern aus.
  3. Wählen Sie auf der Seite Authentifizierung in der Symbolleiste Speichern aus, um Änderungen zu speichern oder mit dem Hinzufügen von Microsoft Entra ID-Administratorbenutzer*innen fortzufahren.

Der native PostgreSQL-Benutzer bzw. die native PostgreSQL-Benutzerin wird auf dem Koordinatorknoten des Clusters erstellt und an alle Workerknoten weitergegeben. Über das Azure-Portal erstellte Rollen weisen das LOGIN-Attribut auf. Dies bedeutet, dass es sich um echte Benutzer*innen handelt, die sich bei der Datenbank anmelden können.

Herstellen einer Verbindung mit Azure Cosmos for PostgreSQL mithilfe der Microsoft Entra ID-Authentifizierung

Die Microsoft Entra ID-Integration funktioniert mit Standard-PostgreSQL-Client-Tools wie psql, die nicht Microsoft Entra ID-fähig sind und beim Herstellen einer Verbindung mit PostgreSQL nur die Angabe von Benutzername und Kennwort unterstützen. In solchen Fällen wird das Microsoft Entra ID-Token als Kennwort übergeben.

Wir haben die folgenden Clients getestet:

  • psql-Befehlszeile: Verwenden Sie die Variable PGPASSWORD, um das Token zu übergeben.
  • Andere libpq-basierte Clients: Beispiele sind gängige Anwendungsframeworks und ORMs (Object-Relational Mappers, objektrelationale Zuordnungen).
  • pgAdmin: Deaktivieren Sie bei der Servererstellung die Option Jetzt verbinden.

Verwenden Sie die folgenden Verfahren, um sich bei Microsoft Entra ID als Benutzer*in von Azure Cosmos DB for PostgreSQL zu authentifizieren. Sie können den Schritten in Azure Cloud Shell, auf einer Azure-VM oder auf Ihrem lokalen Computer folgen.

Anmelden beim Azure-Abonnement des Benutzers

Beginnen Sie mit der Authentifizierung bei Microsoft Entra ID mithilfe der Azure CLI. Dieser Schritt ist in Azure Cloud Shell nicht erforderlich.

az login

Der Befehl öffnet ein Browserfenster zur Microsoft Entra ID-Authentifizierungsseite. Sie müssen Ihre Microsoft Entra ID-Benutzer-ID und Ihr Kennwort angeben.

Der Name des Benutzerkontos, das Sie zur Authentifizierung verwenden (z. B. user@tenant.onmicrosoft.com), ist derjenige, für den im nächsten Schritt das Zugriffstoken generiert wird.

Abrufen des Microsoft Entra ID-Zugriffstokens

Rufen Sie mithilfe der Azure CLI ein Zugriffstoken für den über Azure AD authentifizierten Benutzer bzw. die authentifizierte Benutzerin für den Zugriff auf Azure Cosmos for PostgreSQL ab. Hier sehen Sie ein Beispiel:

az account get-access-token --resource https://token.postgres.cosmos.azure.com

Nach erfolgreicher Authentifizierung gibt Microsoft Entra ID ein Zugriffstoken für das aktuelle Azure-Abonnement zurück:

{
  "accessToken": "[TOKEN]",
  "expiresOn": "[expiration_date_and_time]",
  "subscription": "[subscription_id]",
  "tenant": "[tenant_id]",
  "tokenType": "Bearer"
}

Das Token ist eine Base64-Zeichenfolge. Er kodiert alle Informationen über den authentifizierten Benutzer und ist mit dem Azure Cosmos DB for PostgreSQL-Dienst verbunden. Das Token ist mindestens 5 Minuten bis maximal 90 Minuten gültig. expiresOn definiert die tatsächliche Tokenablaufzeit.

Verwenden des Tokens als Kennwort für die Anmeldung mit psql für Clients

Beim Herstellen einer Verbindung verwenden Sie am besten das Zugriffstoken als PostgreSQL-Benutzerkennwort.

Wenn Sie den psql-Befehlszeilenclient verwenden, muss das Zugriffstoken über die Umgebungsvariable PGPASSWORD übergeben werden. Der Grund dafür ist, dass das Zugriffstoken die Kennwortlänge überschreitet, die psql direkt annehmen kann.

Hier sehen Sie ein Windows-Beispiel:

set PGPASSWORD=<TOKEN value from the previous step>

$env:PGPASSWORD='<TOKEN value from the previous step>'

Hier sehen Sie ein Linux/macOS-Beispiel:

export PGPASSWORD=<TOKEN value from the previous step>

Sie können die vorherigen beiden Schritte auch mithilfe der Befehlsersetzung kombinieren. Der Tokenabruf kann in einer Variablen gekapselt und direkt als Wert für die Umgebungsvariable PGPASSWORD übergeben werden:

export PGPASSWORD=$(az account get-access-token --resource-type oss-rdbms --query "[accessToken]" -o tsv)

Hinweis

Stellen Sie sicher, dass die Variable PGPASSWORD auf das Microsoft Entra ID-Zugriffstoken für Ihr Abonnement für die Microsoft Entra ID-Authentifizierung festgelegt ist. Wenn Sie die Postgres-Rollenauthentifizierung in derselben Sitzung durchführen müssen, können Sie PGPASSWORD auf das Postgres-Rollenkennwort festlegen oder den Wert der PGPASSWORD-Variablen löschen, um das Kennwort interaktiv einzugeben. Bei einem falschen Wert für PGPASSWORD ist die Authentifizierung nicht erfolgreich.

Jetzt können Sie eine Verbindung mit Azure Cosmos DB für PostgreSQL unter Verwendung des Microsoft Entra ID-Benutzerkontos, für das das Zugriffstoken generiert wurde, initiieren. Sie würden es wie gewohnt mit dem Benutzerkonto als Benutzer und ohne den Parameter „Passwort“ in der Befehlszeile tun:

psql "host=mycluster.[uniqueID].postgres.cosmos.azure.com user=user@tenant.onmicrosoft.com dbname=[db_name] sslmode=require"

Verwenden eines Tokens als Kennwort für die Anmeldung mit PgAdmin

Führen Sie die folgenden Schritte aus, um mit einem Microsoft Entra ID-Token eine Verbindung mit PgAdmin herzustellen:

  1. Deaktivieren Sie bei der Servererstellung die Option Jetzt verbinden.
  2. Geben Sie Ihre Serverdetails auf der Registerkarte Verbindung ein, und speichern Sie sie.
    1. Stellen Sie sicher, dass ein*e gültige*r Microsoft Entra ID-Benutzer*in unter Benutzernamen angegeben ist.
  3. Wählen Sie im pgAdmin-Menü Objekt die Option Server verbinden aus.
  4. Geben Sie das Microsoft Entra ID-Tokenkennwort ein, wenn Sie dazu aufgefordert werden.

Hier sind einige wichtige Überlegungen, die Sie beim Herstellen einer Verbindung berücksichtigen sollten:

  • user@tenant.onmicrosoft.com ist der Name des Microsoft Entra ID-Benutzers bzw. der Benutzerin.
  • Stellen Sie sicher, dass Sie die korrekte Schreibweise des Azure-Benutzers verwenden. Bei Microsoft Entra ID-Benutzer- und Gruppennamen wird die Groß-/Kleinschreibung beachtet.
  • Verwenden Sie einen umgekehrten Schrägstrich (\) als Escapezeichen vor Leerzeichen, falls der Name Leerzeichen enthält.
  • Die Gültigkeitsdauer des Zugriffstokens liegt bei 5 bis 90 Minuten. Sie sollten das Zugriffstoken vor dem Initiieren der Anmeldung bei Azure Cosmos for PostgreSQL abrufen.

Sie sind jetzt über die Microsoft Entra ID-Authentifizierung bei Ihrem Azure Cosmos for PostgreSQL-Server authentifiziert.

Verwalten von nativen PostgreSQL-Rollen

Wenn die native PostgreSQL-Authentifizierung im Cluster aktiviert ist, können Sie zusätzlich zur integrierten Rolle „citus“ Postgres-Rollen hinzufügen und löschen. Sie können auch das Kennwort zurücksetzen und Postgres-Berechtigungen für native Rollen ändern.

So löschen Sie eine native PostgreSQL-Benutzerrolle oder ändern das Kennwort

Um Benutzer*innen zu aktualisieren, navigieren Sie zur Seite Authentifizierung für Ihren Cluster, und wählen Sie die Auslassungspunkte (...) neben den entsprechenden Benutzer*innen aus. Die Auslassungspunkte öffnen ein Menü, in dem Benutzer*innen gelöscht oder ihre Kennwörter zurückgesetzt werden können.

Die Rolle citus ist privilegiert und kann nicht gelöscht werden. Die Rolle citus wird jedoch deaktiviert, wenn die Authentifizierungsmethode „Nur Microsoft Entra ID-Authentifizierung“ für den Cluster ausgewählt ist.

So ändern Sie Berechtigungen für eine Benutzerrolle

Neue Benutzerrollen werden häufig verwendet, um Datenbankzugriff mit eingeschränkten Berechtigungen bereitzustellen. Verwenden Sie zum Ändern von Benutzerberechtigungen PostgreSQL-Standardbefehle mithilfe eines Tools wie PgAdmin oder psql. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit dem Cluster.

Um z. B. db_user in PostgreSQL das Lesen von mytable zu erlauben, erteilen Sie die folgende Berechtigung:

GRANT SELECT ON mytable TO db_user;

Verwenden Sie den folgenden Befehl, um die gleichen Berechtigungen für die Microsoft Entra ID-Rolle user@tenant.onmicrosoft.com zu erteilen:

GRANT SELECT ON mytable TO "user@tenant.onmicrosoft.com";

Azure Cosmos DB for PostgreSQL gibt eine GRANT-Anweisung für einzelne Tabellen über den gesamten Cluster weiter und wendet sie auf alle Workerknoten an. Außerdem werden systemweite GRANT-Anweisungen weitergegeben (z. B. für alle Tabellen in einem Schema):

-- applies to the coordinator node and propagates to worker nodes for Postgres role db_user
GRANT SELECT ON ALL TABLES IN SCHEMA public TO db_user;

Oder für die Microsoft Entra ID-Rolle

-- applies to the coordinator node and propagates to worker nodes for Azure AD role user@tenant.onmicrosoft.com
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "user@tenant.onmicrosoft.com";

Nächste Schritte