Freigeben über

Connect-AipService

  • Referenz
Modul:
AIPService

Stellt eine Verbindung mit Azure Information Protection bereit.

Syntax

Connect-AipService
       [-Credential <PSCredential>]
       [-TenantId <Guid>]
       [<CommonParameters>]
Connect-AipService
       [-AccessToken <String>]
       [-TenantId <Guid>]
       [<CommonParameters>]
Connect-AipService
       [-EnvironmentName <AzureRmEnvironment>]
       [<CommonParameters>]

Beschreibung

Das cmdlet Connect-AipService verbindet Sie mit Azure Information Protection, sodass Sie dann administrative Befehle für den Schutzdienst für Ihren Mandanten ausführen können. Dieses Cmdlet kann auch von einem Partnerunternehmen verwendet werden, das Ihren Mandanten verwaltet.

Sie müssen dieses Cmdlet ausführen, bevor Sie die anderen Cmdlets in diesem Modul ausführen können.

Um eine Verbindung mit Azure Information Protection herzustellen, verwenden Sie ein Konto, das eine der folgenden Optionen ist:

  • Ein globaler Administrator für Ihren Office 365-Mandanten.
  • Ein globaler Administrator für Ihren Azure AD-Mandanten. Dieses Konto kann jedoch kein Microsoft-Konto (MSA) oder von einem anderen Azure-Mandanten sein.
  • Ein Benutzerkonto aus Ihrem Mandanten, das über das Cmdlet Add-AipServiceRoleBasedAdministrator Cmdlet Administrative Rechte an Azure Information Protection erteilt hat.
  • Eine Azure AD-Administratorrolle von Azure Information Protection-Administrator, Compliance-Administrator oder Compliance-Datenadministrator.

Trinkgeld

Wenn Sie nicht zur Eingabe Ihrer Anmeldeinformationen aufgefordert werden und eine Fehlermeldung wie Dieses Feature kann nicht ohne Anmeldeinformationenverwendet werden, vergewissern Sie sich, dass Internet Explorer für die Verwendung der integrierten Windows-Authentifizierung konfiguriert ist.

Wenn diese Einstellung nicht aktiviert ist, aktivieren Sie sie, starten Sie Internet Explorer neu, und versuchen Sie dann die Authentifizierung beim Information Protection-Dienst erneut.

Beispiele

Beispiel 1: Herstellen einer Verbindung mit Azure Information Protection und Aufforderung zur Eingabe Ihres Benutzernamens und anderer Anmeldeinformationen

PS C:\> Connect-AipService

Dieser Befehl stellt eine Verbindung mit dem Schutzdienst von Azure Information Protection her. Dies ist die einfachste Möglichkeit, eine Verbindung mit dem Dienst herzustellen, indem Sie das Cmdlet ohne Parameter ausführen.

Sie werden aufgefordert, Ihren Benutzernamen und Ihr Kennwort einzugeben. Wenn Ihr Konto für die Verwendung der mehrstufigen Authentifizierung konfiguriert ist, werden Sie dann zur Eingabe Ihrer alternativen Authentifizierungsmethode aufgefordert und dann mit dem Dienst verbunden.

Wenn Ihr Konto für die Verwendung der mehrstufigen Authentifizierung konfiguriert ist, müssen Sie diese Methode verwenden, um eine Verbindung mit Azure Information Protection herzustellen.

Beispiel 2: Herstellen einer Verbindung mit Azure Information Protection mit gespeicherten Anmeldeinformationen

PS C:\>$AdminCredentials = Get-Credential "Admin@aadrm.contoso.com"
PS C:\> Connect-AipService -Credential $AdminCredentials

Der erste Befehl erstellt ein PSCredential--Objekt und speichert ihren angegebenen Benutzernamen und Das Kennwort in der $AdminCredentials Variablen. Wenn Sie diesen Befehl ausführen, werden Sie aufgefordert, das Kennwort für den von Ihnen angegebenen Benutzernamen einzugeben.

Der zweite Befehl stellt mithilfe der in $AdminCredentialsgespeicherten Anmeldeinformationen eine Verbindung mit Azure Information Protection sicher. Wenn Sie die Verbindung mit dem Dienst trennen und die Verbindung erneut herstellen, während die Variable noch verwendet wird, führen Sie einfach den zweiten Befehl erneut aus.

Beispiel 3: Herstellen einer Verbindung mit Azure Information Protection mit einem Token

PS C:\ > Add-Type -Path "C:\Program Files\WindowsPowerShell\Modules\AIPService\1.0.0.1\Microsoft.IdentityModel.Clients.ActiveDirectory.dll"
PS C:\ > $clientId='90f610bf-206d-4950-b61d-37fa6fd1b224';
PS C:\ > $resourceId = 'https://api.aadrm.com/';
PS C:\ > $userName='admin@contoso.com';
PS C:\ > $password='Passw0rd!';
PS C:\ > $authority = "https://login.microsoftonline.com/common";
PS C:\ > $authContext = New-Object Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext($authority);
PS C:\ > $userCreds = New-Object Microsoft.IdentityModel.Clients.ActiveDirectory.UserPasswordCredential($userName, $password);
PS C:\ > $authResult = [Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContextIntegratedAuthExtensions]::AcquireTokenAsync($authContext, $resourceId, $clientId, $userCreds).Result;
PS C:\ > Import-Module AIPService
PS C:\> Connect-AipService -AccessToken $authResult.AccessToken

In diesem Beispiel wird gezeigt, wie Sie mithilfe des AccessToken-Parameters eine Verbindung mit Azure Information Protection herstellen können, mit dem Sie sich ohne Aufforderung authentifizieren können. Für diese Verbindungsmethode müssen Sie die Client-ID 90f610bf-206d-4950-b61d-37fa6fd1b224 und die Ressourcen-ID *https://api.aadrm.com/*angeben. Nachdem die Verbindung geöffnet wurde, können Sie die administrativen Befehle in diesem modul ausführen, das Sie benötigen.

Nachdem Sie bestätigt haben, dass diese Befehle eine erfolgreiche Verbindung mit Azure Information Protection herstellen, können Sie sie nicht interaktiv ausführen, z. B. aus einem Skript.

Beachten Sie, dass in diesem Beispiel der Benutzername admin@contoso.com mit dem Kennwort Passw0rd verwendet wird. In einer Produktionsumgebung, wenn Sie diese Verbindungsmethode nicht interaktiv verwenden, verwenden Sie zusätzliche Methoden, um das Kennwort zu sichern, sodass es nicht im Klartext gespeichert ist. Verwenden Sie z. B. den Befehl ConvertTo-SecureString, oder verwenden Sie Key Vault, um das Kennwort als Geheimschlüssel zu speichern.

Beispiel 4: Herstellen einer Verbindung mit Azure Information Protection mit Clientzertifikat über die Dienstprinzipalauthentifizierung

PS C:\ > $Thumbprint = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
PS C:\ > $TenantId = 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyy'
PS C:\ > $ApplicationId = '00000000-0000-0000-0000-00000000'
PS C:\> Connect-AipService -CertificateThumbprint $Thumbprint -ApplicationId $ApplicationId -TenantId $TenantId -ServicePrincipal

In diesem Beispiel wird eine Verbindung mit einem Azure-Konto mithilfe der zertifikatbasierten Dienstprinzipalauthentifizierung hergestellt. Der für die Authentifizierung verwendete Dienstprinzipal muss mit dem angegebenen Zertifikat erstellt werden.

Voraussetzungen für dieses Beispiel:

  • Sie müssen das AIPService PowerShell-Modul auf Version 1.0.05 oder höher aktualisieren.
  • Um die Dienstprinzipalauthentifizierung zu aktivieren, müssen Sie dem Dienstprinzipal Lese-API-Berechtigungen (Application.Read.All) hinzufügen.

Weitere Informationen finden Sie unter Erforderliche API-Berechtigungen – Microsoft Information Protection SDK und Verwenden von Azure PowerShell zum Erstellen eines Dienstprinzipals mit einem Zertifikat.

Beispiel 5: Herstellen einer Verbindung mit Azure Information Protection mit geheimem Clientschlüssel über die Dienstprinzipalauthentifizierung

PS C:\ > $TenantId = 'yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyy'
PS C:\ > $ApplicationId = '00000000-0000-0000-0000-00000000'
PS C:\ > $Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $ApplicationId, $SecuredPassword
PS C:\ > Connect-AipService -Credential $Credential -TenantId $TenantId -ServicePrincipal

In diesem Beispiel:

  • Die ersten Eingabeaufforderungen für Dienstprinzipalanmeldeinformationen und speichert sie in der variablen $Credential. Wenn höhergestuft, geben Sie Ihre Anwendungs-ID für den Benutzernamenwert und den Dienstprinzipalschlüssel als Kennwort ein.
  • Der zweite Befehl stellt mithilfe der in der variablen $Credential Variablen gespeicherten Dienstprinzipalanmeldeinformationen eine Verbindung mit dem angegebenen Azure-Mandanten herzustellen. Der parameter ServicePrincipal switch gibt an, dass das Konto als Dienstprinzipal authentifiziert wird.

Um die Dienstprinzipalauthentifizierung zu aktivieren, müssen Sie dem Dienstprinzipal Lese-API-Berechtigungen (Application.Read.All) hinzufügen. Weitere Informationen finden Sie unter Erforderliche API-Berechtigungen – Microsoft Information Protection SDK.

Parameter

-AccessToken

Verwenden Sie diesen Parameter, um eine Verbindung mit Azure Information Protection herzustellen, indem Sie ein Token verwenden, das Sie aus Azure Active Directory abrufen, mithilfe der Client-ID 90f610bf-206d-4950-b61d-37fa6fd1b224 und der Ressourcen-ID https://api.aadrm.com/. Mit dieser Verbindungsmethode können Sie sich nicht interaktiv bei Azure Information Protection anmelden.

Um das Zugriffstoken abzurufen, stellen Sie sicher, dass das Konto, das Sie von Ihrem Mandanten verwenden, keine mehrstufige Authentifizierung (Multi-Factor Authentication, MFA) verwendet. Weitere Informationen hierzu finden Sie in Beispiel 3.

Sie können diesen Parameter nicht mit dem Parameter Credential verwenden.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-ApplicationID

Gibt die Anwendungs-ID des Dienstprinzipals an.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-CertificateThumbprint

Gibt den Zertifikatfingerabdruck eines digitalen X.509-Zertifikats für einen Dienstprinzipal an, der über Berechtigungen zum Ausführen der angegebenen Aktion verfügt.

Typ:String
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-Credential

Gibt ein PSCredential -Objekt an. Um ein PSCredential-Objekt abzurufen, verwenden Sie das Cmdlet Get-Credential. Geben Sie Get-Help Get-Cmdletein, um weitere Informationen zu erfahren.

Das Cmdlet fordert Sie zur Eingabe eines Kennworts auf.

Sie können diesen Parameter nicht mit dem parameter AccessToken verwenden und nicht verwenden, wenn Ihr Konto für die Verwendung der mehrstufigen Authentifizierung (Multi-Factor Authentication, MFA) konfiguriert ist.

Typ:PSCredential
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-EnvironmentName

Gibt die Azure-Instanz für souveräne Clouds an. Gültige Werte sind:

  • AzureCloud: Kommerzielles Angebot von Azure
  • AzureChinaCloud: Von 21Vianet betriebene Azure
  • AzureUSGovernment: Azure Government

Weitere Informationen zur Verwendung von Azure Information Protection mit Azure Government finden Sie unter Azure Information Protection Premium Government Service Description.

Typ:AzureRmEnvironment
Zulässige Werte:AzureCloud, AzureChinaCloud, AzureUSGovernment
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-ServicePrincipal

Gibt an, dass das Cmdlet die Dienstprinzipalauthentifizierung angibt.

Der Dienstprinzipal muss mit dem angegebenen geheimen Schlüssel erstellt werden.

Typ:SwitchParameter
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False

-TenantId

Gibt die Mandanten-GUID an. Das Cmdlet stellt eine Verbindung mit Azure Information Protection für den mandanten, den Sie durch GUID angeben.

Wenn Sie diesen Parameter nicht angeben, stellt das Cmdlet eine Verbindung mit dem Mandanten herstellt, zu dem Ihr Konto gehört.

Typ:Guid
Position:Named
Standardwert:None
Erforderlich:False
Pipelineeingabe akzeptieren:False
Platzhalterzeichen akzeptieren:False