Introducción a las API de administración de Office 365

  • Artículo

Al crear una aplicación que necesita acceso a servicios protegidos, como la API de administración de Office 365, necesita proporcionar un método para que el servicio conozca si la aplicación tiene derechos para obtener acceso a ella. Las API de administración de Office 365 usan Microsoft Entra ID para proporcionar servicios de autenticación que puede usar para conceder derechos a la aplicación para acceder a ellos.

Hay cuatro pasos principales:

  1. Registre la aplicación en Microsoft Entra ID. Para permitir que la aplicación acceda a las API de administración de Office 365, debe registrar la aplicación en Microsoft Entra ID. Esto le permite establecer una identidad para la aplicación y especificar los niveles de permisos necesarios para obtener acceso a las API.

  2. Obtener el consentimiento del administrador del espacio empresarial de Office 365. Un administrador de espacio empresarial de Office 365 tiene que conceder de manera explícita permiso para que la aplicación obtenga acceso a los datos del espacio empresarial mediante las API de administración de Office 365. El proceso de consentimiento es una experiencia basada en explorador que requiere que el administrador de inquilinos inicie sesión en la interfaz de usuario de consentimiento de Microsoft Entra y revise los permisos de acceso que solicita la aplicación y, a continuación, conceda o deniegue la solicitud. Después de conceder la solicitud, la interfaz de usuario redirige al usuario a la aplicación con un código de autorización en la URL. La aplicación realiza una llamada de servicio a servicio a Microsoft Entra ID para intercambiar este código de autorización por un token de acceso, que contiene información sobre el administrador de inquilinos y la aplicación. Es necesario extraer el id. del espacio empresarial del token de acceso y almacenarlo para su uso futuro.

  3. Solicitar tokens de acceso desde Microsoft Entra ID. Con las credenciales de la aplicación configuradas en Microsoft Entra ID, la aplicación solicita tokens de acceso adicionales para un inquilino con consentimiento de forma continuada, sin necesidad de una interacción adicional del administrador de inquilinos. Estos tokens de acceso se denominan tokens solo de aplicación porque no incluyen información sobre el administrador del espacio empresarial.

  4. Llamar a las API de administración de Office 365. Los tokens de acceso solo de aplicación se pasan a las API de administración de Office 365 para autenticar y autorizar la aplicación.

En el diagrama siguiente, se muestra la secuencia de solicitudes de tokens de acceso y consentimiento.

Flujo de autorización de introducción a las API de administración

Importante

Para poder acceder a los datos a través de la API de Actividad de administración de Office 365, debe activar el registro de auditoría unificado para su organización de Office 365. Para ello, active el registro de auditoría de Office 365. Para obtener instrucciones, consulte Activar o desactivar la búsqueda de registros de auditoría de Office 365.

No es necesario habilitar un registro de auditoría unificado si solo usa la API de comunicaciones de servicio de Office 365.

Registrar la aplicación en Microsoft Entra ID

Las API de administración de Office 365 usan Microsoft Entra ID para proporcionar autenticación segura a Office 365 datos de inquilino. Para acceder a las API de administración de Office 365, debe registrar la aplicación en Microsoft Entra ID y, como parte de la configuración, especificará los niveles de permisos que necesita la aplicación para acceder a las API.

Requisitos previos

Para registrar la aplicación en Microsoft Entra ID, necesita una suscripción para Office 365 y una suscripción a Azure que se haya asociado a la suscripción de Office 365. Para empezar, puede usar suscripciones de prueba, tanto para Office 365 como para Azure. Para obtener más información, vea Introducción al programa Office 365 Developer.

Use Azure Portal para registrar la aplicación en Microsoft Entra ID

Después de tener un inquilino de Microsoft con las suscripciones adecuadas, puede registrar la aplicación en Microsoft Entra ID.

  1. Inicie sesión en el Azure Portal, con la credencial de su espacio empresarial de Microsoft que tenga la suscripción a Office 365 que desea usar. También puede acceder a Azure Portal a través de un vínculo que aparece en el panel de navegación izquierdo de la Centro de administración de Microsoft 365.

  2. En el panel de navegación izquierdo, seleccione Microsoft Entra ID (1).

    Página principal de Azure Portal

  3. En la página Microsoft Entra ID, seleccione Registros de aplicaciones (2) y, a continuación, seleccione Nuevo registro (3).

    página Registros de aplicaciones en Microsoft Entra ID

  4. En la página Registros de aplicaciones, seleccione Nuevo registro.

    Aparecerá una nueva página para que inicie el registro de la aplicación.

  5. En la página Registrar una aplicación haga lo siguiente:

    Proceso de registro de la aplicación

    1. Asigne un nombre a la aplicación.

    2. Elija quién puede usar la aplicación y acceder a la API.

    3. Proporcione una dirección URL de redireccionamiento para el redireccionamiento del usuario después de la autenticación, si es necesario.

  6. Haga clic en Registrar para registrar la nueva aplicación.

Configurar las propiedades de la aplicación en Microsoft Entra ID

Ahora que la aplicación está registrada, hay varias propiedades importantes que debe especificar que determinen cómo funciona la aplicación dentro de Microsoft Entra ID y cómo los administradores de inquilinos concederán consentimiento para permitir que la aplicación acceda a sus datos mediante las API de administración de Office 365.

Para obtener más información sobre Microsoft Entra configuración de la aplicación en general, consulte Propiedades del objeto de aplicación.

  1. id. de cliente. Este valor se genera automáticamente mediante Microsoft Entra ID. La aplicación usará este valor al solicitar el consentimiento de los administradores de inquilinos y al solicitar tokens de solo aplicación a Microsoft Entra ID.

  2. aplicación es multiinquilino. Es necesario establecer esta propiedad en YES para permitir a los administradores de espacios empresariales conceder permiso a una aplicación para obtener acceso a sus datos mediante las API de administración de Office 365. Si esta propiedad se establece en NO, la aplicación solo podrá obtener acceso a los datos de su propio espacio empresarial.

  3. dirección URL de respuesta. URL a la que se redirigirá un administrador de espacios empresariales después de conceder el permiso a la aplicación para obtener acceso a sus datos mediante las API de administración de Office 365. Puede configurar varias URL de respuesta si es necesario. Azure establece automáticamente la primera para que coincida con la URL de inicio de sesión que especificó al crear la aplicación, pero puede cambiar este valor si es necesario.

Asegúrese de seleccionar Guardar después de realizar cambios en estas propiedades.

Generar una nueva clave para la aplicación

Las claves, también conocidas como secretos de cliente, se usan al intercambiar un código de autorización para un token de acceso.

  1. En la página Microsoft Entra ID del Azure Portal, seleccione Registros de aplicaciones y, a continuación, seleccione la aplicación.

    Seleccione la aplicación que acaba de registrar

  2. Después de que se muestre la página de la aplicación, seleccione Certificados y secretos (1) en el panel izquierdo. En esta página, puede cargar certificados y crear nuevos secretos de cliente (2).

    Página Certificados y secretos de la aplicación

  3. En la página Certificados y secretos (1), seleccione nuevo secreto de cliente (2), escriba una descripción y seleccione la duración de la clave (3) y, a continuación, seleccione Agregar (4).

    Creación de un secreto de cliente

  4. Después de crear el secreto de cliente, el valor se muestra en secretos de cliente (2). Haga clic en el icono del Portapapeles (3) para copiar el valor del secreto de cliente en el Portapapeles.

    Copie el valor del secreto de cliente en el Portapapeles y guárdelo para usarlo más adelante.

    Importante

    Azure solo muestra el valor del secreto de cliente en el momento de generarlo inicialmente. No puede volver a esta página y recuperar el valor del secreto de cliente más adelante. Asegúrese de copiarlo y guardarlo en una ubicación segura para poder usarlo más adelante.

Configurar un certificado X.509 para habilitar las llamadas entre servicios

Una aplicación que se ejecuta en segundo plano, como un demonio servicio, puede usar las credenciales de cliente para solicitar tokens de acceso solo de aplicación sin solicitar de forma repetida el consentimiento del administrador del espacio empresarial después de recibir el consentimiento inicial.

Para obtener más información, vea Llamadas entre servicios con credenciales de cliente.

Debe configurar un certificado X.509 con la aplicación para que se use como credenciales de cliente al solicitar tokens de acceso de solo aplicación desde Microsoft Entra ID. Este proceso se divide en dos pasos:

  • Obtener un certificado X.509. Puede usar un certificado autofirmado o un certificado emitido por una entidad de certificación de confianza pública.

  • Modificar el manifiesto de la aplicación para incluir la huella digital y la clave pública del certificado.

En las instrucciones siguientes, se muestra cómo usar la herramienta MakeCert de Windows SDK o Visual Studio para generar un certificado autofirmado y exportar la clave pública a un archivo con codificación Base 64.

  1. En la línea de comandos, ejecute el siguiente comando:

     makecert -r -pe -n "CN=MyCompanyName MyAppName Cert" -b 03/15/2015 -e 03/15/2017 -ss my -len 2048

    Nota:

    Al generar el certificado X.509, asegúrese de que la longitud de la clave sea como mínimo de 2048. Las longitudes de clave más cortas no se aceptan como claves válidas.

  2. Abra el complemento MMC de certificados y conéctese a su cuenta de usuario.

  3. Busque el nuevo certificado en la carpeta Personal y exporte la clave pública a un archivo codificado en base64 (por ejemplo, mycompanyname.cer). La aplicación usará este certificado para comunicarse con Microsoft Entra ID, así que asegúrese de conservar también el acceso a la clave privada.

    Nota:

    Puede usar Windows PowerShell para extraer la huella digital y la clave pública con codificación Base 64. Hay otras plataformas que ofrecen herramientas similares para recuperar propiedades de certificados.

  4. En un símbolo del sistema de Windows PowerShell, escriba y ejecute lo siguiente:

     $cer = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2
 $cer.Import("mycer.cer")
 $bin = $cer.GetRawCertData()
 $base64Value = [System.Convert]::ToBase64String($bin)
 $bin = $cer.GetCertHash()
 $base64Thumbprint = [System.Convert]::ToBase64String($bin)
 $keyid = [System.Guid]::NewGuid().ToString()

  5. Guarde los valores de $base64Thumbprint, $base64Value y $keyid para usarlos al actualizar el manifiesto de la aplicación en el siguiente conjunto de pasos.

    Con los valores extraídos del certificado y el identificador de clave generado, ahora debe actualizar el manifiesto de aplicación en Microsoft Entra ID.

  6. En Azure Portal, vaya a Registros de aplicaciones>Todas las aplicaciones, seleccione la aplicación y, a continuación, seleccione manifiesto en el panel izquierdo.

  7. En la barra de navegación superior de la página Manifiesto de (1), seleccione Descargar (2).

    Descargar el manifiesto para poder editarlo

  8. Abra el manifiesto descargado en un editor y reemplace la propiedad keyCredentials vacía por el siguiente JSON:

       "keyCredentials": [
     {
         "customKeyIdentifier" : "$base64Thumbprint_from_above",
         "keyId": "$keyid_from_above",
         "type": "AsymmetricX509Cert",
         "usage": "Verify",
         "value": "$base64Value_from_above"
     }
 ],

    Nota:

    La propiedad KeyCredentials es una colección que permite cargar varios certificados para escenarios de sustitución o certificados X.509 de eliminación para escenarios de peligro.

  9. Guarde los cambios y cargue el archivo de manifiesto de la aplicación actualizado; para ello, haga clic en Administrar manifiesto en la barra de comandos, seleccione Cargar manifiesto, busque el archivo de manifiesto actualizado y, después, selecciónelo.

Especificar los permisos que necesita la aplicación para obtener acceso a las API de administración de Office 365

Por último, tendrá que especificar exactamente qué permisos necesita su aplicación de las API de administración de Office 365. Para hacerlo, agregue acceso a las API de administración de Office 365 a la aplicación y, después, especifique los permisos necesarios.

  1. En Azure Portal, vaya a Registros de aplicaciones>Todas las aplicaciones, seleccione la aplicación y, a continuación, seleccione Permisos de API (1) en el panel izquierdo. Haga clic en Agregar un permiso (2) para mostrar la página de control flotante Solicitar permiso de API (3).

    Agregar permisos de API

  2. En la pestaña API de Microsoft, seleccione API de administración de Office 365 (4).

    Seleccionar las API de administración de Office 365 en la pestaña API de Microsoft

  3. En la página de control flotante, seleccione los siguientes tipos de permisos (3) que requiere la aplicación y, a continuación, haga clic en Agregar permisos

    Seleccionar tipos de permisos para la aplicación

    1. Permisos delegados. Permite que la aplicación cliente realice operaciones en nombre del usuario que ha iniciado sesión, como leer el correo electrónico o modificar el perfil del usuario.

    2. Permisos de aplicación. Permisos que permiten que la aplicación cliente se autentique como sí misma sin la interacción o el consentimiento del usuario, como una aplicación usada por servicios en segundo plano o aplicaciones de demonio.

  4. Las API de administración de Office ahora aparecen en la lista de aplicaciones para las que la aplicación requiere permisos. En permisos de aplicación y permisos delegados, si es necesario, seleccione los permisos que requiere la aplicación. Para obtener más información sobre cada permiso, vea la referencia de API específica.

    Permisos de API para la aplicación

  5. Seleccione Conceder consentimiento de administrador para "nombre de inquilino" para dar su consentimiento a los permisos concedidos a la aplicación.

Después de configurar la aplicación con los permisos necesarios para usar las API de administración de Office 365, un administrador de espacios empresariales tiene que conceder de manera explícita a las aplicaciones dos permisos para obtener acceso a los datos del espacio empresarial mediante las API. Para conceder el consentimiento, el administrador de inquilinos debe iniciar sesión en Microsoft Entra ID mediante la siguiente dirección URL especialmente construida, donde puede revisar los permisos solicitados de la aplicación. Este paso no es necesario al usar las API para obtener acceso a datos desde su propio espacio empresarial.

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id={your_client_id}&redirect_uri={your_redirect_url }

La dirección URL de redireccionamiento debe coincidir o ser una ruta de acceso secundaria en una de las direcciones URL de respuesta configuradas para la aplicación en Microsoft Entra ID.

Por ejemplo:

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e&redirect_uri=http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F

Para probar la URL de consentimiento, péguela en un explorador e inicie sesión con las credenciales de administrador de Office 365 de un espacio empresarial distinto del espacio empresarial que usó para registrar la aplicación. Verá la solicitud para conceder permisos a la aplicación para usar las API de administración de Office.

Página de consentimiento de permisos

Después de seleccionar Aceptar, será redirigido a la página especificada y verá un código en la cadena de consulta.

Por ejemplo:

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

La aplicación usa este código de autorización para obtener un token de acceso de Microsoft Entra ID, del que se puede extraer el identificador de inquilino. Después de extraer y almacenar el id. de espacio empresarial, puede obtener otros tokens de acceso sin que sea necesario que el administrador del espacio empresarial inicie sesión.

Solicitud de tokens de acceso desde Microsoft Entra ID

Hay dos métodos para solicitar tokens de acceso desde Microsoft Entra ID:

  • En el Flujo de concesión de código de autorización, un administrador de espacios empresariales concede el consentimiento explícito, que devuelve un código de autorización a la aplicación. Después, la aplicación intercambia el código de autorización por un token de acceso. Este método es necesario para obtener el consentimiento inicial que necesita la aplicación para obtener acceso a los datos del espacio empresarial mediante la API, y este primer token de acceso es necesario para obtener y almacenar el id. de espacio empresarial.

  • El Flujo de concesión de credenciales de cliente permite a la aplicación solicitar tokens de acceso posteriores cuando expiren los anteriores, sin que sea necesario que el administrador del espacio empresarial inicie sesión y conceda el permiso de manera explícita. Este método tiene que usarse para las aplicaciones que se ejecutan de forma continua en segundo plano mediante llamadas a la API después de conceder el consentimiento inicial del administrador del espacio empresarial.

Solicitar un token de acceso mediante el código de autorización

Una vez que un administrador de inquilinos concede consentimiento, la aplicación recibe un código de autorización como parámetro de cadena de consulta cuando Microsoft Entra ID redirige al administrador de inquilinos a la dirección URL designada.

http://www.mycompany.com/myapp/?code=AAABAAAAvPM1KaPlrEqdFSB...

La aplicación realiza un HTTP REST POST para Microsoft Entra ID para intercambiar el código de autorización por un token de acceso. Como aún no se conoce el id. del espacio empresarial, la solicitud POST se realizará al punto de conexión “común”, que no tiene insertado el id. de espacio empresarial en la URL:

https://login.windows.net/common/oauth2/token

El cuerpo de la llamada POST contiene lo siguiente:

resource=https%3A%2F%2Fmanage.office.com&client_id=a6099727-6b7b-482c-b509-1df309acc563 &redirect_uri= http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F &client_secret={your_client_key}&grant_type=authorization_code&code= AAABAAAAvPM1KaPlrEqdFSB...

Solicitud de ejemplo

POST https://login.windows.net/common/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.windows.net
Content-Length: 944

resource=https%3A%2F%2Fmanage.office.com&client_id=a6099727-6b7b-482c-b509-1df309acc563 &redirect_uri= http%3A%2F%2Fwww.mycompany.com%2Fmyapp%2F &client_secret={your_client_key}&grant_type=authorization_code&code=AAABAAAAvPM1KaPlrEqdFSB...

En el cuerpo de la respuesta, se incluirán varias propiedades, incluido el token de acceso.

Respuesta de ejemplo

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 3265

{"expires_in":"3599","token_type":"Bearer","scope":"ActivityFeed.Read ActivityReports.Read ServiceHealth.Read","expires_on":"1438290275","not_before":"1438286375","resource":"https://manage.office.com","access_token":"eyJ0eX...","refresh_token":"AAABAAA...","id_token":"eyJ0eXAi..."}

El token de acceso devuelto es un token JWT que contiene información sobre el administrador que concedió el permiso y la aplicación que solicita el acceso. En el ejemplo siguiente, se muestra un token sin codificar. La aplicación tiene que extraer el elemento “tid” del id. de espacio empresarial de este token y almacenarlo para que pueda usarse con el fin de solicitar tokens de acceso adicionales cuando expiren, sin la interacción adicional de administrador.

Token de ejemplo

{
  "aud": "https://manage.office.com",
  "iss": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "iat": 1427246416,
  "nbf": 1427246416,
  "exp": 1427250316,
  "ver": "1.0",
  "tid": "41463f53-8812-40f4-890f-865bf6e35190",
  "amr": [
    "pwd"
  ],
  "oid": "1cef1fdb-ff52-48c4-8e4e-dfb5ea83d357",
  "upn": "admin@contoso.onmicrosoft.com",
  "puid": "1003BFFD8EC47CA6",
  "sub": "7XpD5OWAXM1OWmKiVKh1FOkKXV4N3OSRol6mz1pxxhU",
  "given_name": "John",
  "family_name": "Doe",
  "name": "Contoso, Inc.",
  "unique_name": "admin@contoso.onmicrosoft.com",
  "appid": "a6099727-6b7b-482c-b509-1df309acc563",
  "appidacr": "1",
  "scp": "ActivityFeed.Read ServiceHealth.Read",
  "acr": "1"
}

Solicitar un token de acceso mediante las credenciales del cliente

Una vez conocido el identificador de inquilino, la aplicación puede realizar llamadas de servicio a servicio a Microsoft Entra ID para solicitar tokens de acceso adicionales a medida que expiren. Estos tokens solo contienen información sobre la aplicación solicitante, no sobre el administrador que concedió el permiso inicialmente. Para realizar llamadas entre servicios, es necesario que la aplicación use un certificado X.509 para crear la aserción de cliente con el formato de un token de portador JWT con firma SHA256 y con codificación Base 64.

Al desarrollar la aplicación en .NET, puede usar la Biblioteca de autenticación de Microsoft (MSAL) para crear las aserciones del cliente. Otras plataformas de desarrollo necesitan tener bibliotecas parecidas.

Un token JWT sin codificar está formado por un encabezado y una carga que contiene las propiedades siguientes.

HEADER:

{
  "alg": "RS256",
  "x5t": "{thumbprint of your X.509 certificate used to sign the token",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/{tenantid}/oauth2/token",
  "iss": "{your app client ID}",
  "sub": "{your app client ID}",
  "jti": "{random GUID}",
  "nbf": "{epoch time, before which the token is not valid}",
  "exp": "{epoch time, after which the token is not valid}"
}

Token JWT de ejemplo

HEADER:

{
  "alg": "RS256",
  "x5t": "YyfshJC3rPQ-kpGo5dUaiY5t3iU",
}

PAYLOAD:

{
  "aud": "https://login.windows.net/41463f53-8812-40f4-890f-865bf6e35190/oauth2/token",
  "iss": "a6099727-6b7b-482c-b509-1df309acc563",
  "sub": "a6099727-6b7b-482c-b509-1df309acc563",
  "jti": "0ce254c4-81b1-4a2e-8436-9a8c3b49dfb9",
  "nbf": 1427248048,
  "exp": 1427248648,
}

A continuación, la aserción de cliente se pasa a Microsoft Entra ID como parte de una llamada de servicio a servicio para solicitar un token de acceso. Al usar credenciales de cliente para solicitar un token de acceso, use una llamada HTTP POST a un punto de conexión específico de un espacio empresarial, donde se inserta en la URL el id. de espacio empresarial extraído y almacenado anteriormente.

https://login.windows.net/{tenantid}/oauth2/token

El cuerpo de la llamada POST contiene lo siguiente:

resource=https%3A%2F%2Fmanage.office.com&client_id={your_app_client_id}&grant_type=client_credentials&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion={encoded_signed_JWT_token}

Solicitud de ejemplo

POST https://login.windows.net/41463f53-8812-40f4-890f-865bf6e35190/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: login.windows.net
Content-Length: 994

resource=https%3A%2F%2Fmanage.office.com&client_id= a6099727-6b7b-482c-b509-1df309acc563&grant_type=client_credentials &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Ill5ZnNoSkMzclBRLWtwR281ZFVhaVk1dDNpVSJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ud2luZG93cy5uZXRcLzQxNDYzZjUzLTg4MTItNDBmNC04OTBmLTg2NWJmNmUzNTE5MFwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQyNzI0ODY0OCwiaXNzIjoiYTYwOTk3MjctNmI3Yi00ODJjLWI1MDktMWRmMzA5YWNjNTYzIiwianRpIjoiMGNlMjU0YzQtODFiMS00YTJlLTg0MzYtOWE4YzNiNDlkZmI5IiwibmJmIjoxNDI3MjQ4MDQ4LCJzdWIiOiJhNjA5OTcyNy02YjdiLTQ4MmMtYjUwOS0xZGYzMDlhY2M1NjMifQ.vfDrmCjiXgoj2JrTkwyOpr-NOeQTzlXQcGlKGNpLLe0oh4Zvjdcim5C7E0UbI3Z2yb9uKQdx9G7GeqS-gVc9kNV_XSSNP4wEQj3iYNKpf_JD2ikUVIWBkOg41BiTuknRJAYOMjiuBE2a6Wyk-vPCs_JMd7Sr-N3LiNZ-TjluuVzWHfok_HWz_wH8AzdoMF3S0HtrjNd9Ld5eI7MVMt4OTpRfh-Syofi7Ow0HN07nKT5FYeC_ThBpGiIoODnMQQtDA2tM7D3D6OlLQRgLfI8ir73PVXWL7V7Zj2RcOiooIeXx38dvuSwYreJYtdphmrDBZ2ehqtduzUZhaHL1iDvLlw

La respuesta será la misma que antes, pero ahora el token no tendrá las mismas propiedades, ya que no contiene las propiedades del administrador que concedió el permiso.

Respuesta de ejemplo

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1276

{"token_type":"Bearer","expires_in":"3599","expires_on":"1431659094","not_before":"1431655194","resource":"https://manage.office.com","access_token":"eyJ0eXAiOiJKV1QiL..."}

Token de acceso de ejemplo

{
  "aud": "https://manage.office.com",
  "iss": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "iat": 1431655194,
  "nbf": 1431655194,
  "exp": 1431659094,
  "ver": "1.0",
  "tid": "41463f53-8812-40f4-890f-865bf6e35190",
  "roles": [
    "ServiceHealth.Read",
    "ActivityFeed.Read"
  ],
  "oid": "67cb0334-e242-4783-8028-0f39132fb5ad",
  "sub": "67cb0334-e242-4783-8028-0f39132fb5ad",
  "idp": "https://sts.windows.net/41463f53-8812-40f4-890f-865bf6e35190/",
  "appid": "a6099727-6b7b-482c-b509-1df309acc563",
  "appidacr": "1"
}

Crear una aplicación

Ahora que ha registrado la aplicación en Microsoft Entra ID y la ha configurado con los permisos necesarios, está listo para compilar la aplicación. Estos son algunos de los aspectos clave que se deben tener en cuenta al diseñar y compilar la aplicación.

  • Experiencia de consentimiento. Para obtener el consentimiento de sus clientes, debe dirigirlos en un explorador al sitio web de Microsoft Entra, utilizando la dirección URL especialmente construida descrita anteriormente, y debe tener un sitio web al que Microsoft Entra ID redirigirá al administrador una vez que concedan su consentimiento. El sitio web necesita extraer el código de autorización de la URL y usarlo para solicitar un token de acceso desde el que podrá obtener el id. del espacio empresarial.

  • Almacenar el id. de espacio empresarial en el sistema. Esto será necesario al solicitar tokens de acceso desde Microsoft Entra ID y al llamar a las API de administración de Office.

  • Administrar tokens de acceso. Necesitará un componente que solicite y administre los tokens de acceso según sea necesario. Si la aplicación realiza llamadas a la API de forma periódica, puede solicitar tokens a petición; o bien, si realiza llamadas a la API de forma continua para recuperar datos, puede solicitar tokens a intervalos regulares (por ejemplo, cada 45 minutos).

  • Implemente un agente de escucha de webhook. Según sea necesario para la API determinada que use.

  • Almacenamiento y recuperación de datos. Necesita un componente que recupere datos de cada espacio empresarial, bien mediante la realización de sondeos continuos o en respuesta a notificaciones de webhook, según la API específica que use.