Connect-AipService

Se conecta a Azure Information Protection.

Syntax

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

Description

El cmdlet Connect-AipService le conecta a Azure Information Protection para poder ejecutar comandos administrativos para el servicio de protección para el inquilino. Este cmdlet también lo puede usar una empresa asociada que administre su inquilino.

Debe ejecutar este cmdlet para poder ejecutar los otros cmdlets de este módulo.

Para conectarse a Azure Information Protection, use una cuenta que sea una de las siguientes:

  • Un administrador global para el inquilino de Office 365.
  • Administrador global del inquilino de Azure AD. Sin embargo, esta cuenta no puede ser una cuenta Microsoft (MSA) ni de otro inquilino de Azure.
  • Una cuenta de usuario del inquilino a la que se han concedido derechos administrativos a Azure Information Protection mediante el cmdlet Add-AipServiceRoleBasedAdministrator.
  • Un rol de administrador de Azure AD de administrador de Azure Information Protection, administrador de cumplimiento o administrador de datos de cumplimiento.

Sugerencia

Si no se le solicitan las credenciales y ve un mensaje de error como No se puede usar esta característica sin credenciales, compruebe que Internet Explorer está configurado para usar la autenticación integrada de Windows.

Si esta configuración no está habilitada, habilite, reinicie Internet Explorer y vuelva a intentar la autenticación en el servicio Information Protection.

Ejemplos

Ejemplo 1: Conectarse a Azure Information Protection y solicitar el nombre de usuario y otras credenciales

PS C:\> Connect-AipService

Este comando se conecta al servicio de protección desde Azure Information Protection. Esta es la manera más sencilla de conectarse al servicio mediante la ejecución del cmdlet sin parámetros.

Se le pedirá el nombre de usuario y la contraseña. Si la cuenta está configurada para usar la autenticación multifactor, se le pedirá el método alternativo de autenticación y, a continuación, se le conectará al servicio.

Si la cuenta está configurada para usar la autenticación multifactor, debe usar este método para conectarse a Azure Information Protection.

Ejemplo 2: Conexión a Azure Information Protection con credenciales almacenadas

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

El primer comando crea un objeto PSCredential y almacena el nombre de usuario y la contraseña especificados en la variable $AdminCredentials . Al ejecutar este comando, se le pedirá la contraseña del nombre de usuario que especificó.

El segundo comando se conecta a Azure Information Protection mediante las credenciales almacenadas en $AdminCredentials. Si se desconecta del servicio y vuelve a conectarse mientras la variable sigue en uso, simplemente vuelva a ejecutar el segundo comando.

Ejemplo 3: Conexión a Azure Information Protection con un 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

En este ejemplo se muestra cómo puede conectarse a Azure Information Protection mediante el parámetro AccessToken, que le permite autenticarse sin un aviso. Este método de conexión requiere que especifique el identificador de cliente 90f610bf-206d-4950-b61d-37fa6fd1b224 y el identificador *https://api.aadrm.com/*de recurso . Una vez abierta la conexión, puede ejecutar los comandos administrativos desde este módulo que necesita.

Después de confirmar que estos comandos se conectan correctamente a Azure Information Protection, podría ejecutarlos de forma no interactiva, por ejemplo, desde un script.

Tenga en cuenta que, con fines ilustrativos, en este ejemplo se usa el nombre de usuario de admin@contoso.com con la contraseña de Passw0rd. En un entorno de producción cuando se usa este método de conexión de forma no interactiva, use métodos adicionales para proteger la contraseña de modo que no se almacene en texto no cifrado. Por ejemplo, use el comando ConvertTo-SecureString o use Key Vault para almacenar la contraseña como secreto.

Ejemplo 4: Conexión a Azure Information Protection con certificado de cliente mediante autenticación de entidad de servicio

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

En este ejemplo se conecta a una cuenta de Azure mediante la autenticación de entidad de servicio basada en certificados. La entidad de servicio usada para la autenticación debe crearse con el certificado especificado.

Requisitos previos para este ejemplo:

  • Debe actualizar el módulo de PowerShell de AIPService a la versión 1.0.05 o posterior.
  • Para habilitar la autenticación de entidad de servicio, debe agregar permisos de API de lectura (Application.Read.All) a la entidad de servicio.

Para obtener más información, consulte Permisos de API necesarios: Microsoft Information Protection SDK y Uso de Azure PowerShell para crear una entidad de servicio con un certificado.

Ejemplo 5: Conexión a Azure Information Protection con secreto de cliente mediante autenticación de entidad de servicio

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

En este ejemplo:

  • El primer comando solicita las credenciales de la entidad de servicio y las almacena en la variable $Credential. Cuando se promueve, escriba el identificador de la aplicación para el valor de nombre de usuario y el secreto de la entidad de servicio como contraseña.
  • El segundo comando se conecta al inquilino de Azure especificado mediante las credenciales de la entidad de servicio almacenadas en la $Credential variable . El ServicePrincipal parámetro switch indica que la cuenta se autentica como una entidad de servicio.

Para habilitar la autenticación de entidad de servicio, debe agregar permisos de API de lectura (Application.Read.All) a la entidad de servicio. Para obtener más información, consulte Permisos de API necesarios: SDK de Microsoft Information Protection.

Parámetros

-AccessToken

Use este parámetro para conectarse a Azure Information Protection mediante un token que adquiera de Azure Active Directory mediante el identificador de cliente 90f610bf-206d-4950-b61d-37fa6fd1b224 y el identificador https://api.aadrm.com/de recurso . Este método de conexión le permite iniciar sesión en Azure Information Protection de forma no interactiva.

Para obtener el token de acceso, asegúrese de que la cuenta que usa desde el inquilino no usa la autenticación multifactor (MFA). Consulte el ejemplo 3 para saber cómo hacerlo.

No puede usar este parámetro con el parámetro Credential .

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

-ApplicationID

Especifica el identificador de aplicación de la entidad de servicio.

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

-CertificateThumbprint

Especifica la huella digital del certificado de un certificado X.509 de clave pública digital para una entidad de servicio que tenga permisos para realizar la acción especificada.

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

-Credential

Especifica un objeto PSCredential . Para obtener un objeto PSCredential, use el cmdlet Get-Credential. Para obtener más información, escriba Get-Help Get-Cmdlet.

El cmdlet le pide una contraseña.

No puede usar este parámetro con el parámetro AccessToken y no usarlo si la cuenta está configurada para usar la autenticación multifactor (MFA).

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

-EnvironmentName

Especifica la instancia de Azure para nubes soberanas. Los valores válidos son:

  • AzureCloud: Oferta comercial de Azure
  • AzureChinaCloud: Azure operado por 21Vianet
  • AzureUSGovernment: Azure Government

Para más información sobre el uso de Azure Information Protection con Azure Government, consulte Descripción del servicio Azure Information Protection Premium Government.

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 el cmdlet especifica la autenticación de la entidad de servicio.

La entidad de servicio debe crearse con el secreto especificado.

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

-TenantId

Especifica el GUID del inquilino. El cmdlet se conecta a Azure Information Protection para el inquilino especificado por GUID.

Si no especifica este parámetro, el cmdlet se conecta al inquilino al que pertenece su cuenta.

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