Nota: La integración con PowerShell requiere una suscripción Pro o Enterprise de ShareGate Migrate. No está disponible en el plan Essentials.

Este artículo es exclusivo para la integración de PowerShell de ShareGate Migrate. La autenticación solo de aplicación te permite ejecutar migraciones de buzones desde PowerShell sin una cuenta de usuario con la sesión iniciada. En lugar de credenciales de usuario, ShareGate Migrate se autentica mediante un registro de aplicaciones de Azure (app registration). Esto es ideal para migraciones automatizadas o programadas en entornos empresariales.

Durante la configuración, obtendrás dos valores para pasar a los comandos de PowerShell de ShareGate: el Application (client) ID y el Directory (tenant) ID.

Antes de comenzar

Suscripción Pro o Enterprise de ShareGate Migrate
Acceso de Global Administrator tanto en el inquilino de Microsoft 365 de origen como en el de destino, necesario para crear el app registration y otorgar el consentimiento del administrador

Inquilino único o multiinquilino

Conocer la diferencia entre estos dos términos te ayudará a elegir la configuración adecuada:

Un app registration es el modelo de la aplicación. Reside en el inquilino principal (el inquilino donde lo creas) y define la identidad de la aplicación, los permisos de API y los certificados.
Una enterprise application (también llamada entidad de servicio o service principal) es la instancia local de esa aplicación dentro de un inquilino específico. Es sobre esta instancia donde otorgas el consentimiento del administrador y asignas roles.

Elige según la cantidad de inquilinos que migres:

Un solo inquilino (single-tenant): la aplicación se usa únicamente en el inquilino donde la registras. En Supported account types, elige My organization only. Para migrar entre dos inquilinos, repite la configuración completa en cada uno.
Multiinquilino (multi-tenant): un único app registration en tu inquilino principal, reutilizado en varios inquilinos. Es la opción habitual para consultores, proveedores de servicios administrados y migraciones de origen a destino. En Supported account types, elige Multiple Entra ID tenants y deja seleccionado Allow all tenants. Luego, das el consentimiento a la aplicación en cada inquilino adicional y le asignas allí el rol Exchange Administrator. Consulta Configura inquilinos adicionales más abajo.

Con una aplicación multiinquilino, creas el objeto de credenciales una sola vez y pasas un -TenantId diferente a Connect-MicrosoftOnline para cada inquilino.

Configura el app registration

Haz esto en tu inquilino principal. Para una aplicación de un solo inquilino, repite el proceso en cada inquilino de origen o destino. Para una aplicación multiinquilino, hazlo una sola vez y luego sigue Configura inquilinos adicionales más abajo.

Opción 1: Configuración manual en el portal de Azure

Paso 1: Crea el app registration

Inicia sesión en el Microsoft Entra admin center como Global Administrator.
Ve a Entra ID > App registrations > New registration.
Asígnale un nombre a la aplicación (por ejemplo, ShareGate Mailbox Migration).
En Supported account types, elige la opción que corresponda a tu escenario. Consulta Inquilino único o multiinquilino más arriba.
Deja el campo Redirect URI vacío por ahora.
Haz clic en Register.
En la página Overview, copia el Application (client) ID y el Directory (tenant) ID. Los usarás con New-AzureApplication y Connect-MicrosoftOnline. Anota también el Display name o el Object ID para la asignación de roles del paso 4.

Paso 2: Agrega una reply URL

Nota: Este paso es obligatorio para las aplicaciones multiinquilino. El consentimiento del administrador no se completará sin al menos una reply URL. https://go.sharegate.com/vmen es una página de destino de ShareGate que confirma que el consentimiento se realizó correctamente.

En tu app registration, ve a Authentication y haz clic en + Add Redirect URI.
En el panel Web platform, en Redirect URI, ingresa https://go.sharegate.com/vmen.
Haz clic en Configure.

Paso 3: Agrega los API permissions

Elige uno de los dos métodos a continuación.

Opción A: De forma manual en el portal de Azure

Ve a API permissions > Add a permission.
Agrega cada uno de los Application permissions que se indican a continuación (no Delegated). Los permisos de Microsoft Graph y los de Office 365 Exchange Online se agregan por separado.
Haz clic en Grant admin consent for [your tenant] y confirma.

Permisos de Microsoft Graph:

`Mail.ReadWrite`	Elementos de correo
`Calendars.ReadWrite`	Eventos de calendario
`Contacts.ReadWrite`	Contactos
`MailboxSettings.ReadWrite`	Configuración del buzón
`User.Read.All`	Listado de buzones, perfiles de usuario
`Directory.Read.All`	Validación de licencias
`Organization.Read.All`	Validación de dominios

Permisos de Office 365 Exchange Online:

Nota: Estos permisos se encuentran en Office 365 Exchange Online, no en Microsoft Graph. Usa Exchange.ManageAsApp, no Exchange.ManageAsAppV2.

`full_access_as_app`	Buzones de archivo y de grupo (EWS)
`Exchange.ManageAsApp`	Administración de buzones

Opción B: Mediante el manifiesto de la aplicación

Esto te permite agregar todos los permisos a la vez pegando un fragmento JSON, lo que evita errores de selección manual.

En tu app registration, ve a Manifest.

Busca el arreglo requiredResourceAccess y reemplázalo por el siguiente:

"requiredResourceAccess": [
    {
        "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
        "resourceAccess": [
            { "id": "dc50a0fb-09a3-484d-be87-e023b12c6440", "type": "Role" },
            { "id": "dc890d15-9560-4a4c-9b7f-a736ec74ec40", "type": "Role" }
        ]
    },
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            { "id": "ef54d2bf-783f-4e0f-bca1-3210c0444d99", "type": "Role" },
            { "id": "6918b873-d17a-4dc1-b314-35f528134491", "type": "Role" },
            { "id": "7ab1d382-f21e-4acd-a863-ba3e13f7da61", "type": "Role" },
            { "id": "e2a3a72e-5f79-4c64-b1b1-878b674786c9", "type": "Role" },
            { "id": "6931bccd-447a-43d1-b442-00a195474933", "type": "Role" },
            { "id": "498476ce-e0fe-48b0-b801-37ba7e2685c6", "type": "Role" },
            { "id": "df021288-bdef-4463-88db-98f22de89214", "type": "Role" }
        ]
    }
]

Haz clic en Save.
Ve a API permissions, haz clic en Grant admin consent for [your tenant] y confirma.

Paso 4: Asigna el rol Exchange Administrator

Nota: Este paso es obligatorio para la administración de archivos, las retenciones legales (litigation holds) y las operaciones de tamaño de buzón.

Exchange Administrator es un rol a nivel de directorio, por lo que no puedes asignarlo directamente desde la página Roles and administrators del app registration. Los pasos a continuación te llevan a la vista de asignación a nivel de directorio.

En tu app registration, ve a Roles and administrators.
En la línea que dice "Directory-level roles have inherited access to this resource and can only be assigned at the directory level here", haz clic en here para abrir la asignación de roles a nivel de directorio.
Busca y selecciona Exchange Administrator.
Haz clic en + Add assignments y luego en Select member(s).
Busca el Display name u Object ID de tu app registration, selecciónalo y haz clic en Select.
Haz clic en Next y luego en Assign.

Opción 2: Configuración rápida con PowerShell (recomendado)

Este script automatiza todo lo de la Opción 1: crea el app registration, agrega la reply URL, otorga todos los permisos necesarios y asigna el rol Exchange Administrator. No crea una credencial; eso lo haces en Agrega una credencial, más abajo.

Primero, instala el SDK de PowerShell de Microsoft Graph (una sola vez):

Install-Module Microsoft.Graph -Scope CurrentUser

Luego, ejecuta lo siguiente con la sesión iniciada como Global Administrator del inquilino principal. Configura $multiTenant = $true para una aplicación multiinquilino.

$ErrorActionPreference = 'Stop'
$displayName  = 'ShareGate Mailbox Migration'
$multiTenant  = $false   # set to $true to allow the app to be consented in other tenants
$replyUrl     = 'https://go.sharegate.com/vmen'

$signInAudience = if ($multiTenant) { 'AzureADMultipleOrgs' } else { 'AzureADMyOrg' }

# Well-known resource app IDs
$graphAppId = '00000003-0000-0000-c000-000000000000'   # Microsoft Graph
$exoAppId   = '00000002-0000-0ff1-ce00-000000000000'   # Office 365 Exchange Online

# Application permissions to grant
$graphRoleIds = @(
    'e2a3a72e-5f79-4c64-b1b1-878b674786c9',  # Mail.ReadWrite
    'ef54d2bf-783f-4e0f-bca1-3210c0444d99',  # Calendars.ReadWrite
    '6918b873-d17a-4dc1-b314-35f528134491',  # Contacts.ReadWrite
    '6931bccd-447a-43d1-b442-00a195474933',  # MailboxSettings.ReadWrite
    'df021288-bdef-4463-88db-98f22de89214',  # User.Read.All
    '7ab1d382-f21e-4acd-a863-ba3e13f7da61',  # Directory.Read.All
    '498476ce-e0fe-48b0-b801-37ba7e2685c6'   # Organization.Read.All
)
$exoRoleIds = @(
    'dc50a0fb-09a3-484d-be87-e023b12c6440',  # full_access_as_app
    'dc890d15-9560-4a4c-9b7f-a736ec74ec40'   # Exchange.ManageAsApp
)
$exchangeAdminRoleId = '29232cdf-9323-42fd-ade2-1d097af3e4de'  # Exchange Administrator (built-in)

# 1. Sign in
Connect-MgGraph -Scopes 'Application.ReadWrite.All','AppRoleAssignment.ReadWrite.All','RoleManagement.ReadWrite.Directory'

# 2. Create the app registration
$requiredResourceAccess = @(
    @{ ResourceAppId = $graphAppId; ResourceAccess = @($graphRoleIds | ForEach-Object { @{ Id = $_; Type = 'Role' } }) },
    @{ ResourceAppId = $exoAppId;   ResourceAccess = @($exoRoleIds   | ForEach-Object { @{ Id = $_; Type = 'Role' } }) }
)
$app = New-MgApplication -DisplayName $displayName -SignInAudience $signInAudience `
    -Web @{ RedirectUris = @($replyUrl) } `
    -RequiredResourceAccess $requiredResourceAccess

# 3. Create the service principal
$sp = New-MgServicePrincipal -AppId $app.AppId
Start-Sleep -Seconds 10   # let the service principal replicate

# 4. Grant admin consent
$graphSp = Get-MgServicePrincipal -Filter "appId eq '$graphAppId'"
$exoSp   = Get-MgServicePrincipal -Filter "appId eq '$exoAppId'"
foreach ($roleId in $graphRoleIds) {
    New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -PrincipalId $sp.Id -ResourceId $graphSp.Id -AppRoleId $roleId | Out-Null
}
foreach ($roleId in $exoRoleIds) {
    New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $sp.Id -PrincipalId $sp.Id -ResourceId $exoSp.Id -AppRoleId $roleId | Out-Null
}

# 5. Assign the Exchange Administrator role
New-MgRoleManagementDirectoryRoleAssignment -PrincipalId $sp.Id -RoleDefinitionId $exchangeAdminRoleId -DirectoryScopeId '/' | Out-Null

# 6. Output the values you'll use with ShareGate
[pscustomobject]@{
    DisplayName   = $displayName
    ApplicationId = $app.AppId
    TenantId      = (Get-MgContext).TenantId
} | Format-List

Copia el ApplicationId y el TenantId de la salida. Los usarás cuando te conectes. Para una aplicación multiinquilino, esto configura únicamente tu inquilino principal. Sigue Configura inquilinos adicionales más abajo para cada inquilino adicional.

Configura inquilinos adicionales

Nota: Esta sección se aplica únicamente a las aplicaciones multiinquilino. El app registration y su credencial residen en tu inquilino principal. Para usar la aplicación en otro inquilino, un administrador de ese inquilino debe otorgarle su consentimiento y asignarle el rol Exchange Administrator. Repite este proceso para cada inquilino adicional.

Un administrador del inquilino adicional debe abrir la siguiente URL en un navegador, reemplazar los marcadores de posición e iniciar sesión como Global Administrator de ese inquilino:

https://login.microsoftonline.com/<additional-tenant-id-or-domain>/adminconsent?client_id=<application-client-id>

Después de revisar y aceptar los permisos, el navegador redirige a la página de confirmación de ShareGate. Esto aprovisiona la enterprise application (entidad de servicio) de la aplicación en ese inquilino.

2. Asigna el rol Exchange Administrator en el inquilino adicional

Con la sesión iniciada en el inquilino adicional:

Ve a Entra ID > Roles & admins.
Busca y selecciona Exchange Administrator.
Haz clic en + Add assignments y luego en Select member(s).
Busca la aplicación por su Display name o Application (client) ID, selecciónala y haz clic en Select.
Haz clic en Next y luego en Assign.

Agrega una credencial

New-AzureApplication admite dos métodos de autenticación basados en certificados. Elige uno.

Opción A: Certificado (desde un archivo)

Ve a Certificates & secrets > Certificates > Upload certificate.
Sube tu archivo de clave pública .cer o .pem.
Mantén la clave privada (.pfx) accesible desde PowerShell en tiempo de ejecución.

Opción B: Huella digital del certificado (Almacén de certificados de Windows)

Instala el certificado (con la clave privada) en el Almacén de certificados de Windows de la máquina que ejecuta la migración.
Ve a Certificates & secrets > Certificates > Upload certificate y sube la clave pública.
Anota la huella digital. La pasarás directamente a New-AzureApplication.

Nota: En el caso de una aplicación multiinquilino, sube la credencial una sola vez al app registration de tu inquilino principal. La misma credencial funciona en todos los inquilinos en los que se haya dado el consentimiento a la aplicación.

Conéctate desde ShareGate

Crea un objeto de credenciales con New-AzureApplication y, luego, conéctate con Connect-MicrosoftOnline. Pasa el inquilino de destino con -TenantId.

# Build a credential object from a certificate thumbprint
$azureApp = New-AzureApplication -ClientId <application-client-id> -Thumbprint <certificate-thumbprint>

# Connect to a tenant
Connect-MicrosoftOnline -TenantId <directory-tenant-id> -AzureApplication $azureApp

Con una aplicación multiinquilino, reutiliza el mismo objeto $azureApp y cambia -TenantId para cada inquilino:

Connect-MicrosoftOnline -TenantId <source-tenant-id> -AzureApplication $azureApp
Connect-MicrosoftOnline -TenantId <destination-tenant-id> -AzureApplication $azureApp

Nota: Si la política de seguridad de tu organización impide otorgar alguno de los permisos necesarios, agrega -AllowMissingPermissions a Connect-MicrosoftOnline para conectarte de todos modos. Las operaciones que dependan del permiso faltante fallarán con errores Forbidden. Este parámetro solo flexibiliza la verificación de permisos después de que la autenticación se realice correctamente; no resuelve un inicio de sesión fallido.

Limitaciones conocidas

Los calendarios de grupo no son compatibles con la autenticación solo de aplicación. Se trata de una limitación de la API de Microsoft Graph que afecta a todas las herramientas de migración.

Este artículo fue traducido con inteligencia artificial. En caso de duda, consulta la versión original en inglés.

Configura un registro de aplicaciones de Azure para migraciones de buzones de correo mediante PowerShell