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 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 Administratorrechte für Azure Information Protection erteilt wurde, indem Sie das Cmdlet Add-AipServiceRoleBasedAdministrator verwenden.
  • Eine Azure AD-Administratorrolle von Azure Information Protection Administrator, Complianceadministrator oder Compliancedatenadministrator.

Tipp

Wenn Sie nicht für Ihre Anmeldeinformationen aufgefordert werden und eine Fehlermeldung wie " Dieses Feature kann nicht ohne Anmeldeinformationen verwendet werden" angezeigt werden, stellen Sie sicher, 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 wiederholen Sie dann die Authentifizierung an den Information Protection Dienst.

Beispiele

Beispiel 1: Herstellen einer Verbindung mit Azure Information Protection und aufgefordert werden, Ihren Benutzernamen und andere Anmeldeinformationen zu erhalten

PS C:\> Connect-AipService

Dieser Befehl verbindet sich mit dem Schutzdienst von Azure Information Protection. 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 zu erhalten. Wenn Ihr Konto für die Verwendung der mehrstufigen Authentifizierung konfiguriert ist, werden Sie dann zur 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 Ihr Kennwort in der $AdminCredentials Variablen. Wenn Sie diesen Befehl ausführen, werden Sie aufgefordert, das Kennwort für den von Ihnen angegebenen Benutzernamen zu erhalten.

Der zweite Befehl verbindet sich mit Azure Information Protection mithilfe der Anmeldeinformationen, die in $AdminCredentials gespeichert sind. Wenn Sie die Verbindung vom Dienst trennen und die Verbindung erneut herstellen, während die Variable weiterhin 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 eine Verbindung mit Azure Information Protection mithilfe des AccessToken-Parameters herstellen können, mit dem Sie sich ohne Aufforderung authentifizieren können. Diese Verbindungsmethode erfordert, dass Sie die Client-ID 90f610bf-206d-4950-b61d-37fa6fd1b224 und die Ressourcen-ID *https://api.aadrm.com/*angeben. Nachdem die Verbindung geöffnet ist, können Sie dann die administrativen Befehle aus diesem Modul ausführen, die Sie benötigen.

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

Beachten Sie, dass dieses Beispiel den Benutzernamen admin@contoso.com mit dem Kennwort von Passw0rd verwendet! Verwenden Sie in einer Produktionsumgebung, wenn Sie diese Verbindungsmethode nicht interaktiv verwenden, zusätzliche Methoden, um das Kennwort zu sichern, damit sie nicht in klarem Text gespeichert wird. Verwenden Sie beispielsweise den Befehl ConvertTo-SecureString oder verwenden Sie Key Vault, um das Kennwort als geheim 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 Dienstprinzipal, der für die Authentifizierung verwendet wird, 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 api-Berechtigungen (Application.Read.All) zum Dienstprinzipal 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 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:

  • Der erste Befehl fordert zur Eingabe von Dienstprinzipal-Anmeldeinformationen auf und speichert sie in der $Credential Variable. Geben Sie beim Aufsteigen Ihre Anwendungs-ID für den Benutzernamenwert und den Dienstprinzipalschlüssel als Kennwort ein.
  • Der zweite Befehl verbindet sich mit dem angegebenen Azure-Mandanten mit den in der $Credential Variablen gespeicherten Dienstprinzipalanmeldeinformationen. Der ServicePrincipal Switch-Parameter gibt an, dass das Konto als Dienstprinzipal authentifiziert wird.

Um die Dienstprinzipalauthentifizierung zu aktivieren, müssen Sie api-Berechtigungen (Application.Read.All) zum Dienstprinzipal 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 mithilfe eines Token herzustellen, das Sie von Azure Active Directory erwerben, mithilfe der Client-ID 90f610bf-206d-4950-b61d-37fa6fd1b224 und der Ressourcen-IDhttps://api.aadrm.com/. Mit dieser Verbindungsmethode können Sie sich bei Azure Information Protection nicht interaktiv anmelden.

Um das Zugriffstoken abzurufen, stellen Sie sicher, dass das Konto, das Sie von Ihrem Mandanten verwenden, keine mehrstufige Authentifizierung (MFA) verwendet. Siehe Beispiel 3, wie Sie dies tun können.

Dieser Parameter kann nicht mit dem Parameter "Anmeldeinformationen " verwendet werden.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationID

Gibt die Anwendungs-ID des Dienstprinzipals an.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CertificateThumbprint

Gibt den Zertifikat-Fingerabdruck eines digitalen öffentlichen Schlüssels X.509-Zertifikats für einen Dienstprinzipal an, der über Berechtigungen zum Ausführen der angegebenen Aktion verfügt.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Credential

Gibt ein PSCredential-Objekt an. Verwenden Sie zum Abrufen eines PSCredential-Objekts das Get-Credential-Cmdlet. Geben Sie Folgendes ein, um weitere Informationen zu erhalten: Get-Help Get-Cmdlet.

Das Cmdlet fordert Sie zur Eingabe eines Kennworts auf.

Sie können diesen Parameter nicht mit dem AccessToken-Parameter verwenden und nicht verwenden, wenn Ihr Konto für die mehrstufige Authentifizierung (MFA) konfiguriert ist.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EnvironmentName

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

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

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

Type:AzureRmEnvironment
Accepted values:AzureCloud, AzureChinaCloud, AzureUSGovernment
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ServicePrincipal

Gibt an, dass das Cmdlet die Dienstprinzipalauthentifizierung angibt.

Der Dienstprinzipal muss mit dem angegebenen Geheimen erstellt werden.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TenantId

Gibt die Mandanten-GUID an. Das Cmdlet verbindet mit Azure Information Protection für den Mandanten, den Sie von GUID angeben.

Wenn Sie diesen Parameter nicht angeben, verbindet das Cmdlet den Mandanten, zu dem Ihr Konto gehört.

Type:Guid
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False