Autenticación y autorización para la API de Exchange Online Administración

Nota:

Las características descritas en este artículo están actualmente en versión preliminar, no están disponibles en todas las organizaciones y están sujetas a cambios.

En este artículo se tratan los requisitos de autenticación y autorización para usar puntos de conexión para la API de Exchange Online Administración.

La API de Exchange Online Administración proporciona una manera basada en REST de ejecutar cmdlets de PowerShell específicos, reemplazando escenarios heredados de Exchange Web Services (EWS). Para obtener más información, consulte Introducción a la API de Exchange Online Administración.

Para acceder a la API de Administración, la aplicación debe establecer su identidad, obtener los permisos adecuados y seguir los procedimientos recomendados para el control seguro de tokens. En un nivel alto, el proceso implica los pasos clave siguientes:

Registro de una aplicación en Microsoft Entra ID

Cree un registro de aplicación para establecer una identidad para la aplicación y configurar las credenciales (secreto de cliente o certificado). Este registro permite a la aplicación solicitar tokens de Microsoft Entra ID.
Asignación de permisos de API necesarios

Agregue los ámbitos de OAuth necesarios al registro de la aplicación:
- Flujo delegado: Exchange.ManageV2.
- Flujo de solo aplicación: Exchange.ManageAsAppV2.
Paso 3: Asignar permisos de RBAC

Exchange Online usa el control de acceso basado en rol (RBAC) para determinar qué puntos de conexión, cmdlets y objetos puede administrar el autor de la llamada. Asigne los roles de RBAC adecuados al usuario (para el acceso delegado) o a la entidad de servicio de la aplicación (para el acceso de solo aplicación).
Paso 4: Obtención de un token de acceso

Use flujos de OAuth 2.0 para adquirir tokens de Microsoft Entra ID:
- Flujo delegado para el acceso basado en el usuario.
- Flujo de solo aplicación para el acceso de servicio a servicio.
Paso 5: Uso del token de acceso

Paso 1: Registro de una aplicación en Microsoft Entra ID

Para llamar a la API de Exchange Online Administración, primero debe registrar la aplicación en Microsoft Entra ID. Una aplicación es como un objeto de clase. Una entidad de servicio es como una instancia de la clase . Para obtener más información, consulte Objetos de aplicación y entidad de servicio en Microsoft Entra ID. Para obtener un flujo visual detallado sobre cómo crear aplicaciones en Microsoft Entra ID, vea https://aka.ms/azuread-app.

Abra el Centro de administración Microsoft Entra en https://entra.microsoft.com.
En el cuadro de búsqueda de la parte superior de la página, escriba Registros de aplicaciones y selecciónelo en los resultados.
En la página Registros de aplicaciones, seleccione Nuevo registro.
En la página Registrar una aplicación , configure los valores de la aplicación:
- Nombre: escriba un nombre descriptivo (por ejemplo, Exchange Administración cliente de API).
- Tipos de cuenta admitidos: seleccione uno de los valores siguientes:
  - Aplicaciones de una sola organización: seleccione Solo cuentas en este directorio organizativo.
  - Escenarios delegados multiinquilino: seleccione Cuentas en cualquier directorio organizativo.
- URI de redireccionamiento (opcional): necesario para el flujo delegado.
  - Plataforma: seleccione Web.
  - URI: escriba la dirección URL donde se envía el token de acceso (por ejemplo, https://localhost para las pruebas).
Cuando haya terminado en la página Registrar una aplicación , seleccione Registrar.

Se le llevará a la página Información general de la aplicación que registró. Permanezca en la página para el paso siguiente.

Nota:

No puede crear credenciales para aplicaciones nativas porque no se pueden usar para llamadas de servicio a servicio automatizadas.

Paso 2: Asignación de permisos de API necesarios

En la página Información general de la aplicación que creó en el paso anterior, seleccione Permisos de API en la sección Administrar .
En la página Permisos de API de la aplicación, seleccione Agregar un permiso.
En el control flotante Solicitar permisos de API que se abre, seleccione la pestaña API que usa mi organización, escriba Office 365 Exchange Online en el cuadro de búsqueda y, a continuación, selecciónelo en los resultados.
En el control flotante ¿Qué tipo de permisos necesita la aplicación? , realice una de las siguientes selecciones:
- Flujo de solo aplicación: seleccione Permisos de aplicación, expanda Exchange, seleccione Exchange.ManageAsAppV2 y, a continuación, seleccione Agregar permisos.
- Flujo delegado: seleccione Permisos delegados, expanda Exchange, seleccione Exchange.ManageV2 y, a continuación, seleccione Agregar permisos.
De nuevo en la página Permisos de API , compruebe que se muestran las selecciones del paso anterior:
- > Office 365 Exchange Online Exchange.ManageAsApp:
  - Tipo: Aplicación
  - Administración consentimiento necesario: Sí
- > Office 365 Exchange Online Exchange.ManageV2:
  - Tipo: delegado
  - Administración consentimiento necesario: Sí
Seleccione Conceder consentimiento de administrador para, revise el cuadro de diálogo de confirmación y seleccione Sí.

Paso 3: Asignar permisos de RBAC

Después de registrar la aplicación y conceder permisos de API, debe configurar roles de RBAC de Exchange. Los ámbitos de OAuth permiten que la aplicación obtenga tokens, pero RBAC determina qué cmdlets y objetos puede administrar el autor de la llamada. Sin las asignaciones de roles de RBAC adecuadas, incluso los tokens válidos producen un error: 403 Prohibido.

Usa los pasos de una de las subsecciones siguientes en función de la naturaleza de la aplicación.

Permisos para el flujo delegado (usuario)

Para escenarios delegados, el usuario en cuyo nombre la aplicación adquiere el token debe tener asignados los roles de RBAC necesarios en Exchange Online. Ejemplos de roles comunes:

Administración de destinatarios para las operaciones de buzón y carpeta.
Administración de la organización para la configuración de nivel de organización.
Administración de la organización de solo visualización para operaciones de organización de solo lectura.

Asigne estos roles mediante el Centro de administración de Exchange o Exchange Online PowerShell. Para obtener instrucciones, consulte Administración de grupos de roles en Exchange Online.

Permisos para el flujo de solo aplicación

En escenarios de solo aplicación, la entidad de servicio que representa la aplicación debe tener permisos suficientes. Tiene las siguientes opciones:

Asignar roles Microsoft Entra (recomendados por simplicidad): conceda un rol de Microsoft Entra integrado a la aplicación empresarial. Por ejemplo, administrador de Exchange para permisos de Exchange Online completos:
1. En el Centro de administración Microsoft Entra de https://entra.microsoft.com, seleccione Roles & administradores.
2. En roles y administradores | En la página Todos los roles , seleccione el rol Administrador de Exchange haciendo clic en cualquier lugar de la fila que no sea la casilla situada junto a la primera columna.
3. En el administrador de Exchange | Página Asignaciones que se abre, seleccione Agregar asignaciones, elija la aplicación y, a continuación, seleccione Confirmar.
Asignar grupos de roles RBAC de Exchange integrados o personalizados (privilegios mínimos): cree o use grupos de roles personalizados existentes en Exchange Online que contengan solo los cmdlets que necesita la aplicación y agreguen la entidad de servicio a esos grupos. Este enfoque evita privilegios amplios y se alinea con la seguridad con privilegios mínimos. Para obtener más información, consulte Autenticación de solo aplicación en Exchange Online PowerShell.

En la tabla siguiente se muestra el rol RBAC integrado necesario para cada punto de conexión.

Punto de conexión	Grupo de roles de Exchange necesario
/OrganizationConfig /AcceptedDomain	Administración de la organización de solo visualización
/Buzón /MailboxFolderPermission /DistributionGroupMember /DynamicDistributionGroupMember	Recipient Management

Para un control aún más pormenorizado, considere la posibilidad de usar grupos de roles personalizados que incluyan solo los roles de administración específicos (conjuntos de cmdlets) que necesita la aplicación. Este enfoque sigue la seguridad con privilegios mínimos y reduce el riesgo en comparación con roles amplios, como administrador de Exchange o administrador global, que superan el ámbito necesario para las operaciones típicas Administración API.

Paso 4: Obtención de un token de acceso

Para llamar a la API de Exchange Online Administración, la aplicación debe obtener un token de acceso de OAuth 2.0 de Microsoft Entra ID. Como se mencionó anteriormente, Administración API admite los siguientes flujos:

Flujo de código de autorización (delegado) con token de actualización: la aplicación actúa en nombre de un usuario que ha iniciado sesión y también puede obtener un token de actualización para la renovación silenciosa si la solicitud incluye el offline_access ámbito.
Flujo de credenciales de cliente (solo aplicación): la aplicación actúa como sí misma (sin usuario). Se usa para escenarios de servicio o en segundo plano. Los tokens de actualización no se emiten en este flujo.

Use el /.default ámbito del recurso al solicitar tokens (por ejemplo, https://outlook.office365.com/.default). Este método indica a Microsoft Entra ID que emita un token que contenga los permisos de aplicación (roles) concedidos anteriormente para ese recurso.

Flujo de código de autorización (delegado) con token de actualización

Use este flujo cuando necesite el contexto de usuario. Para obtener un token de actualización, debe solicitarlo offline_access en las solicitudes de autorización y token. Para obtener más información, vea Actualizar tokens en los Plataforma de identidad de Microsoft y Ámbitos y permisos en el Plataforma de identidad de Microsoft.

El usuario debe autorizar a la aplicación para que actúe en su nombre. La aplicación redirige al usuario al punto de /authorize conexión de la Plataforma de identidad de Microsoft. A través de este punto de conexión, Microsoft Entra ID inicia sesión al usuario y solicita su consentimiento para los permisos que solicita la aplicación. Después del consentimiento, Microsoft Entra ID devuelve un código de autorización a la aplicación. A continuación, la aplicación puede canjear este código en el /token punto de conexión de la Plataforma de identidad de Microsoft por un token de acceso.

En el ejemplo siguiente se muestra una solicitud al punto de /authorize conexión. En la dirección URL de la solicitud, llame al /authorize punto de conexión y especifique las propiedades necesarias y recomendadas como parámetros de consulta. Por ejemplo:

GET https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/authorize
    ?client_id=<ClientID>
    &response_type=code
    &redirect_uri=<RedirectURI> # must exactly match the app registration
    &response_mode=query
    &scope=https://outlook.office365.com/.default offline_access
    &state=12345

Los parámetros se describen en la tabla siguiente:

Parámetro	Obligatorio	Descripción
TenantID	Obligatorio	Organización en la que se solicita permiso. El valor puede ser el GUID de TenantID o el nombre descriptivo.
client_id	Obligatorio	Identificador de cliente asignado a la aplicación por el portal de registro. También conocido como appId.
response_type	Obligatorio	Debe incluir el valor del flujo `code` de código de autorización de OAuth 2.0.
redirect_uri	Recomendado	El URI de redireccionamiento de la aplicación en formato codificado por URL, donde la aplicación envía y recibe respuestas de autenticación. Debe coincidir con uno de los URI de redireccionamiento que registró en el portal de registro de aplicaciones.
ámbito	Obligatorio	Una lista separada por espacios de los permisos de API de Exchange Online Administración a los que desea que el usuario dé su consentimiento. Estos permisos pueden incluir permisos de recursos (`https://outlook.office365.com/.default` en este escenario) y ámbitos de OIDC, como `offline_access`, lo que indica que la aplicación necesita un token de actualización para el acceso de larga duración a los recursos.
response_mode	Recomendado	Especifica el método para devolver el token resultante a la aplicación. Los valores válidos son `query` o `form_post`.
state	Recomendado	Valor incluido en la solicitud que también se devuelve en la respuesta del token. Puede ser una cadena de cualquier contenido. Normalmente se usa un valor aleatorio y único para evitar ataques de falsificación de solicitudes entre sitios. Esta propiedad también codifica información sobre el estado del usuario en la aplicación antes de que se produjera la solicitud de autenticación, como la página o vista en la que se encontraba.

El usuario inicia sesión y da su consentimiento. Microsoft Entra ID redirige a con redirect_uri?code=<authorization_code>.
El uso offline_access de habilita la emisión de un token de actualización más adelante. Para obtener más información, vea Actualizar tokens en los Plataforma de identidad de Microsoft y Ámbitos y permisos en el Plataforma de identidad de Microsoft.

Paso 2: Canjear el código de autorización por tokens

La aplicación usa el código de autorización del paso anterior para solicitar un token de acceso mediante el envío de una solicitud POST al /token punto de conexión.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                  # confidential clients only
&grant_type=authorization_code
&code=<authorization_code>
&redirect_uri=<RedirectURI>
&scope=https://outlook.office365.com/.default offline_access

Los parámetros se describen en la tabla siguiente:

Parámetro	Obligatorio	Descripción
TenantID	Obligatorio	Organización en la que se solicita permiso. El valor puede ser el GUID de TenantID o el nombre descriptivo.
client_id	Obligatorio	Identificador de cliente asignado a la aplicación por el portal de registro. También conocido como appId.
grant_type	Obligatorio	El valor debe ser `authorization_code` para el flujo de código de autorización.
ámbito	Obligatorio	Lista de ámbitos separados por espacios. Los ámbitos que las solicitudes de aplicación deben ser equivalentes a o un subconjunto de los ámbitos solicitados en Paso 1: Enviar al usuario para iniciar sesión y dar su consentimiento.
código	Obligatorio	El código de autorización que obtuvo en Paso 1: Enviar al usuario para iniciar sesión y dar su consentimiento.
redirect_uri	Obligatorio	El mismo valor de URI de redireccionamiento que usó para adquirir el código de autorización en Paso 1: Enviar al usuario para iniciar sesión y dar su consentimiento.
client_secret	Necesario para aplicaciones web	Secreto de cliente que creó en el portal de registro de aplicaciones de la aplicación.

Una respuesta correcta incluye:

access_token:Portador. Normalmente, unos 60 minutos.
refresh_token: presente, porque offline_access se solicitó.
id_token:Opcional. Se devuelve si se solicitó el ámbito openid . Para obtener más información, consulte Plataforma de identidad de Microsoft tipos de aplicaciones y flujos de autenticación y Actualizar tokens en el Plataforma de identidad de Microsoft.

Sugerencia

Almacene el valor tenantID (tid) de las notificaciones de token. Lo necesita para formar Administración direcciones URL de API y futuras solicitudes de token. Para obtener más información, consulte Plataforma de identidad de Microsoft tipos de aplicaciones y flujos de autenticación.

Paso 3: Actualizar el token de acceso de forma silenciosa (sin aviso del usuario)

Los tokens de acceso son de corta duración y la aplicación debe actualizarlos después de que expiren para seguir accediendo a los recursos. La aplicación actualiza un token de acceso mediante el envío de otra solicitud POST al punto de /token conexión:

Proporcione en refresh_token lugar de en code el cuerpo de la solicitud.
Especifique refresh_token en lugar de authorization_code como el grant_type.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>
&grant_type=refresh_token
&refresh_token=<refresh_token>
&scope=https://outlook.office365.com/.default offline_access

Los parámetros se describen en la tabla siguiente:

Parámetro	Obligatorio	Descripción
TenantID	Obligatorio	Organización en la que se solicita permiso. El valor puede ser el GUID de TenantID o el nombre descriptivo.
client_id	Obligatorio	Identificador de cliente asignado a la aplicación por el portal de registro. También conocido como appId.
grant_type	Obligatorio	El valor debe ser `refresh_token`.
refresh_token	Obligatorio	El refresh_token que obtuvo la aplicación durante la solicitud de token en paso 2: Canjear el código de autorización por tokens.
ámbito	Obligatorio	Lista de ámbitos separados por espacios. Los ámbitos que las solicitudes de aplicación deben ser equivalentes a o un subconjunto de los ámbitos que solicitó en Paso 2: Canjear el código de autorización por tokens.
client_secret	Necesario para aplicaciones web	Secreto de cliente que creó en el portal de registro de aplicaciones de la aplicación.

Una respuesta correcta incluye los siguientes resultados:

Devuelve un nuevo access_token y, a menudo, un nuevo refresh_token para reemplazar el anterior.
Los tokens de actualización duran más que los tokens de acceso. El valor predeterminado es de aproximadamente 90 días para los clientes confidenciales y de 24 horas para los URI de redireccionamiento de SPA. Los tokens que se pueden revocar en cualquier momento, por lo que controlan la reautoría cuando sea necesario. Para obtener más información, vea Actualizar tokens en el Plataforma de identidad de Microsoft.

Flujo de credenciales de cliente (solo aplicación)

Use este flujo para las llamadas de servicio a servicio sin un usuario. Después de que el administrador dé su consentimiento a los permisos de aplicación (por ejemplo, Exchange.ManageAsAppV2) y asigne los roles de RBAC necesarios, solicite un token con las propias credenciales de la aplicación. No se emite ningún token de actualización. Solicite nuevos tokens de acceso según sea necesario.

Para adquirir un token de acceso, envíe una solicitud POST al punto de conexión de la /token plataforma de identidad. En esta solicitud, el cliente usa el secreto de cliente.

POST https://login.microsoftonline.com/<TenantID>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id=<ClientID>
&client_secret=<ClientSecret>                   # or client assertion (certificate)
&grant_type=client_credentials
&scope=https://outlook.office365.com/.default

Los parámetros se describen en la tabla siguiente:

Parámetro	Condición	Descripción
TenantID	Obligatorio	Organización en la que se solicita permiso. El valor puede ser el GUID de TenantID o el nombre descriptivo.
client_id	Obligatorio	Identificador de aplicación asignado a la aplicación por el portal de registro.
ámbito	Obligatorio	Uri del identificador de aplicación del recurso con el `.default` sufijo . Para la API de Exchange Online Administración, el URI del identificador de aplicación de recursos es `https://outlook.office365.com/`, por lo que el valor de ámbito es `https://outlook.office365.com/.default`. Este valor informa al punto de conexión de Plataforma de identidad de Microsoft para que incluya todos los permisos de nivel de aplicación con el consentimiento del administrador en el token de acceso.
client_secret	Obligatorio	Secreto de cliente que generó para la aplicación en el portal de registro de aplicaciones. Compruebe que el valor está codificado con dirección URL.
grant_type	Obligatorio	El valor debe ser `client_credentials`.

Paso 5: Uso del token de acceso

Después de obtener un token de acceso como se describe en Paso 4: Obtener un token de acceso, incluya el token de acceso en el encabezado Authorization para cada llamada API posterior:

POST https://outlook.office365.com/adminapi/v2.0/<TenantID>/OrganizationConfig
Authorization: Bearer <access_token>
Content-Type: application/json

 { "CmdletInput": { "CmdletName": "Get-OrganizationConfig" } }

Uso de la biblioteca de autenticación de Microsoft (MSAL)

Este artículo contiene los detalles de protocolo necesarios al crear manualmente solicitudes HTTP sin procesar para obtener tokens para los secretos de cliente. En las aplicaciones de producción, use una biblioteca de autenticación integrada o compatible para obtener tokens de seguridad y llamar a api web protegidas. Por ejemplo, la biblioteca de autenticación de Microsoft (MSAL).

MSAL y otras bibliotecas de autenticación admitidas simplifican el proceso controlando los detalles para que pueda centrarse en la funcionalidad de la aplicación. Por ejemplo:

Validación.
Control de cookies.
Almacenamiento en caché de tokens.
Conexiones seguras.

Microsoft mantiene una amplia selección de ejemplos de código que muestran las bibliotecas de autenticación admitidas con el Plataforma de identidad de Microsoft. Para acceder a estos ejemplos de código, consulte Plataforma de identidad de Microsoft ejemplos de código.

Para obtener ejemplos sobre cómo obtener tokens mediante certificados, consulte Plataforma de identidad de Microsoft y el flujo de credenciales de cliente de OAuth 2.0.

Last updated on 2025-11-17

Compartir a través de

Autenticación y autorización para la API de Exchange Online Administración

Paso 1: Registro de una aplicación en Microsoft Entra ID

Paso 2: Asignación de permisos de API necesarios

Paso 3: Asignar permisos de RBAC

Permisos para el flujo delegado (usuario)

Permisos para el flujo de solo aplicación

Paso 4: Obtención de un token de acceso

Flujo de código de autorización (delegado) con token de actualización

Paso 1: Enviar al usuario para iniciar sesión y dar su consentimiento

Paso 2: Canjear el código de autorización por tokens

Paso 3: Actualizar el token de acceso de forma silenciosa (sin aviso del usuario)

Flujo de credenciales de cliente (solo aplicación)

Paso 5: Uso del token de acceso

Uso de la biblioteca de autenticación de Microsoft (MSAL)

Recursos adicionales