Connect-AipService

Referência

Módulo:: AIPService

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

Syntax

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ê ao Azure Proteção de Informações para que você possa executar comandos administrativos para o serviço de proteção do seu locatário. Esse cmdlet também pode ser usado por uma empresa parceira que gerencie seu locatário.

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

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

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

Dica

Se você não tiver solicitado 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 Proteção de Informações.

Exemplos

Exemplo 1: conectar-se ao Azure Proteção de Informações e ser solicitado para seu nome de usuário e outras credenciais

PS C:\> Connect-AipService

Esse comando se conecta ao serviço de proteção do Azure Proteção de Informações. 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 ao Azure Proteção de Informações.

Exemplo 2: Conectar-se ao Azure Proteção de Informações 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 o nome de usuário e a senha especificados na variável $AdminCredentials . Ao executar esse comando, você será solicitado a obter a senha do nome de usuário especificado.

O segundo comando se conecta ao Azure Proteção de Informações 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 ao Azure Proteção de Informações 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 ao Azure Proteção de Informações 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 *https://api.aadrm.com/*do recurso. 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 ao Azure Proteção de Informações, você pode executá-los de forma não interativa, por exemplo, de um script.

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

Exemplo 4: Conectar-se ao Azure Proteção de Informações 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 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 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 – Proteção de Informações da Microsoft SDK e Use Azure PowerShell para criar uma entidade de serviço com um certificado.

Exemplo 5: Conectar-se ao Azure Proteção de Informações 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 da entidade de serviço e as armazena na $Credential variável. 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 $Credential variável. O ServicePrincipal parâmetro de comutador 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 – Proteção de Informações da Microsoft SDK.

Parâmetros

-AccessToken

Use esse parâmetro para se conectar ao Azure Proteção de Informações usando um token adquirido do Azure Active Directory, usando a ID do cliente 90f610bf-206d-4950-b61d-37fa6fd1b224 e a ID https://api.aadrm.com/do recurso. Esse método de conexão permite que você entre no Azure Proteção de Informações 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.

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

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

-ApplicationID

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

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

-CertificateThumbprint

Especifica a impressão digital de 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.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 lhe solicita um 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).

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 Governamental

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

Type:	AzureRmEnvironment
Accepted values:	AzureCloud, AzureChinaCloud, AzureUSGovernment
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

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

-TenantId

Especifica o GUID do locatário. O cmdlet se conecta ao 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.

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