Partilhar via

Connect-AipService

  • Referência
Módulo:
AIPService

Conecta-se à Proteção de Informações do Azure.

Sintaxe

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

Description

O cmdlet Connect-AipService conecta você à Proteção de Informações do Azure para que você possa executar comandos administrativos para o serviço de proteção para seu locatário. Esse cmdlet também pode ser usado por uma empresa parceira que gerencia seu locatário.

Você deve executar este cmdlet antes de poder executar os outros cmdlets neste módulo.

Para se conectar à Proteção de Informações do Azure, use uma conta que seja uma das seguintes:

  • Um administrador global para o seu inquilino do Office 365.
  • Um administrador global para seu locatário do Azure AD. No entanto, essa conta não pode ser uma conta da Microsoft (MSA) ou de outro locatário do Azure.
  • Uma conta de usuário do seu locatário que recebeu direitos administrativos para a Proteção de Informações do Azure usando o cmdlet Add-AipServiceRoleBasedAdministrator.
  • Uma função de administrador do Azure AD de administrador da Proteção de Informações do Azure, administrador de conformidade ou administrador de dados de conformidade.

Dica

Se você não for solicitado a fornecer suas credenciais e vir uma mensagem de erro como Não é possível usar esse recurso sem credenciais, verifique se o Internet Explorer está configurado para usar a autenticação integrada do Windows.

Se essa configuração não estiver habilitada, habilite-a, reinicie o Internet Explorer e tente autenticação novamente no serviço Proteção de Informações.

Exemplos

Exemplo 1: Conectar-se à Proteção de Informações do Azure e ser solicitado a fornecer seu nome de usuário e outras credenciais

PS C:\> Connect-AipService

Este comando liga-se ao serviço de proteção da Proteção de Informações do Azure. Essa é a maneira mais simples de se conectar ao serviço, executando o cmdlet sem parâmetros.

Ser-lhe-á pedido o seu nome de utilizador e palavra-passe. Se a sua conta estiver configurada para utilizar a autenticação multifator, ser-lhe-á então pedido o método alternativo de autenticação e, em seguida, ligado ao serviço.

Se sua conta estiver configurada para usar a autenticação multifator, você deverá usar esse método para se conectar à Proteção de Informações do Azure.

Exemplo 2: Conectar-se à Proteção de Informações do Azure com credenciais armazenadas

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

O primeiro comando cria um objeto PSCredential e armazena seu nome de usuário e senha especificados na variável $AdminCredentials. Quando executa este comando, é-lhe solicitada a palavra-passe para o nome de utilizador que especificou.

O segundo comando se conecta à Proteção de Informações do Azure usando as credenciais armazenadas no $AdminCredentials. Se você se desconectar do serviço e se reconectar enquanto a variável ainda estiver em uso, basta executar novamente o segundo comando.

Exemplo 3: Conectar-se à Proteção de Informações do Azure com um 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

Este exemplo mostra como você pode se conectar à Proteção de Informações do Azure usando o parâmetro AccessToken, que permite autenticar sem um prompt. Esse método de conexão requer que você especifique o ID do cliente 90f610bf-206d-4950-b61d-37fa6fd1b224 e o ID do recurso *https://api.aadrm.com/*. Depois que a conexão estiver aberta, você poderá executar os comandos administrativos desse módulo necessários.

Depois de confirmar que esses comandos resultam na conexão bem-sucedida com a Proteção de Informações do Azure, você pode executá-los de forma não interativa, por exemplo, a partir de um script.

Observe que, para fins de ilustração, este exemplo usa o nome de usuário de admin@contoso.com com a senha de Passw0rd! Em um ambiente de produção, quando você usa esse método de conexão de forma não interativa, use métodos adicionais para proteger a senha para que ela não seja armazenada em texto não criptografado. Por exemplo, use o comando ConvertTo-SecureString ou use o Cofre da Chave para armazenar a senha como um segredo.

Exemplo 4: Conectar-se à Proteção de Informações do Azure com certificado de cliente por meio da Autenticação da Entidade de Serviço

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

Este exemplo se conecta a uma conta do Azure usando a autenticação da entidade de serviço baseada em certificado. A entidade de serviço usada para autenticação deve ser criada com o certificado especificado.

Pré-requisitos para este exemplo:

  • Você deve atualizar o módulo AIPService PowerShell para a versão 1.0.05 ou posterior.
  • Para habilitar a autenticação da entidade de serviço, você deve adicionar permissões de API de leitura (Application.Read.All) à entidade de serviço.

Para obter mais informações, consulte Permissões de API necessárias - SDK do Microsoft Information Protection e Usar o Azure PowerShell para criar uma entidade de serviço com um certificado.

Exemplo 5: Conectar-se à Proteção de Informações do Azure com segredo do cliente por meio da Autenticação da Entidade de Serviço

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

Neste exemplo:

  • O primeiro comando solicita credenciais da entidade de serviço e as armazena na variável $Credential. Quando promovido, insira o ID do aplicativo para o valor do nome de usuário e o segredo da entidade de serviço como a senha.
  • O segundo comando se conecta ao locatário do Azure especificado usando as credenciais da entidade de serviço armazenadas na variável $Credential. O parâmetro ServicePrincipal switch indica que a conta é autenticada como uma entidade de serviço.

Para habilitar a autenticação da entidade de serviço, você deve adicionar permissões de API de leitura (Application.Read.All) à entidade de serviço. Para obter mais informações, consulte Permissões de API necessárias - SDK da Proteção de Informações da Microsoft.

Parâmetros

-AccessToken

Use esse parâmetro para se conectar à Proteção de Informações do Azure usando um token adquirido do Azure Ative Directory, usando a ID do cliente 90f610bf-206d-4950-b61d-37fa6fd1b224 e a ID do recurso https://api.aadrm.com/. Esse método de conexão permite que você entre na Proteção de Informações do Azure de forma não interativa.

Para obter o token de acesso, certifique-se de que a conta que você usa do seu locatário não está usando autenticação multifator (MFA). Consulte o Exemplo 3 para saber como fazer isso.

Não é possível usar esse parâmetro com o parâmetro Credential.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ApplicationID

Especifica a ID do aplicativo da entidade de serviço.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CertificateThumbprint

Especifica a impressão digital do certificado de um certificado X.509 de chave pública digital para uma entidade de serviço que tenha permissões para executar a ação determinada.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Credential

Especifica um objeto PSCredential. Para obter um objeto PSCredential , use o cmdlet Get-Credential. Para obter mais informações, digite Get-Help Get-Cmdlet.

O cmdlet solicita uma senha.

Não é possível usar esse parâmetro com o parâmetro AccessToken e não usá-lo se sua conta estiver configurada para usar autenticação multifator (MFA).

Tipo:PSCredential
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-EnvironmentName

Especifica a instância do Azure para nuvens soberanas. Os valores válidos são:

  • AzureCloud: oferta comercial do Azure
  • AzureChinaCloud: Azure operado pela 21Vianet
  • AzureUSGovernment: Azure Government

Para obter mais informações sobre como usar a Proteção de Informações do Azure com o Azure Government, consulte Azure Information Protection Premium Government Service Description.

Tipo:AzureRmEnvironment
Valores aceites:AzureCloud, AzureChinaCloud, AzureUSGovernment
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ServicePrincipal

Indica que o cmdlet especifica a autenticação da entidade de serviço.

A entidade de serviço deve ser criada com o segredo especificado.

Tipo:SwitchParameter
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-TenantId

Especifica o GUID do locatário. O cmdlet se conecta à Proteção de Informações do Azure para o locatário especificado pelo GUID.

Se você não especificar esse parâmetro, o cmdlet se conectará ao locatário ao qual sua conta pertence.

Tipo:Guid
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False