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

Ponta

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 novamente a autenticação no serviço de Proteção de Informações.

Exemplos

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

PS C:\> Connect-AipService

Esse comando se conecta 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.

Você será solicitado a fornecer seu nome de usuário e senha. Se sua conta estiver configurada para usar a autenticação multifator, você será solicitado a usar seu método alternativo de autenticação e, em seguida, conectado 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. Ao executar esse comando, você será solicitado a fornecer a senha para o nome de usuário especificado.

O segundo comando se conecta à Proteção de Informações do Azure usando as credenciais armazenadas em $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 que você se autentique sem um prompt. Esse método de conexão exige que você especifique a ID do cliente 90f610bf-206d-4950-b61d-37fa6fd1b224 e a ID do recurso *https://api.aadrm.com/*. Depois que a conexão estiver aberta, você poderá executar os comandos administrativos deste módulo de que precisa.

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

Observe que, para fins ilustrativos, este exemplo usa o nome de usuário de admin@contoso.com com a senha de Passw0rd! Em um ambiente de produção ao usar 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 claro. Por exemplo, use o comando ConvertTo-SecureString ou use o Key Vault para armazenar a senha como um segredo.

Exemplo 4: Conectar-se à Proteção de Informações do Azure com o certificado do 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 de 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 do PowerShell do AIPService 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 – do SDK de Proteção de Informações da Microsoft 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 o 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 de entidade de serviço e as armazena na variável $Credential. Quando promovido, insira a 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 de opção ServicePrincipal 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 –do 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 Active 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, verifique se a conta que você usa do seu locatário não está usando a MFA (autenticação multifator). Veja o Exemplo 3 para saber como você pode fazer isso.

Você não pode usar esse parâmetro com o parâmetro Credential.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ApplicationID

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

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 tem permissões para executar a ação determinada.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 a MFA (autenticação multifator).

Tipo:PSCredential
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-EnvironmentName

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

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

Para obter mais informações sobre como usar a Proteção de Informações do Azure com o Azure Governamental, consulte Descrição do Serviço Premium governamental da Proteção de Informações do Azure.

Tipo:AzureRmEnvironment
Valores aceitos:AzureCloud, AzureChinaCloud, AzureUSGovernment
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False