Obtener acceso sin un usuario
Para llamar a Microsoft Graph, una aplicación debe obtener un token de acceso de la Plataforma de identidad de Microsoft. Este token de acceso incluye información sobre si la aplicación está autorizada para acceder a Microsoft Graph en nombre de un usuario que ha iniciado sesión o con su propia identidad. En este artículo se proporcionan instrucciones sobre cómo una aplicación puede acceder a Microsoft Graph con su propia identidad, también denominada acceso de solo aplicación.
En este artículo se detallan las solicitudes HTTP sin procesar implicadas para que una aplicación llame a Microsoft Graph con su propia identidad mediante un flujo popular denominado flujo de concesión de credenciales de cliente de OAuth 2.0. Como alternativa, puede evitar escribir solicitudes HTTP sin procesar y usar una biblioteca de autenticación compatible o compilada por Microsoft que administre muchos de estos detalles automáticamente y le ayude a obtener tokens de acceso y a llamar a Microsoft Graph. Para obtener más información, consulte Uso de la biblioteca de autenticación de Microsoft (MSAL).
Requisitos previos
Antes de continuar con los pasos de este artículo:
- Comprenda los conceptos de autenticación y autorización en el Plataforma de identidad de Microsoft. Para obtener más información, consulte Conceptos básicos de autenticación y autorización.
- Registre la aplicación con Microsoft Entra ID. Para obtener más información, consulte Registro de una aplicación con el Plataforma de identidad de Microsoft.
Pasos de autenticación y autorización
Para que una aplicación obtenga autorización y acceso a Microsoft Graph mediante el flujo de credenciales de cliente, debe seguir estos cinco pasos:
- Registre la aplicación con Microsoft Entra ID.
- Configure los permisos de aplicación de Microsoft Graph en la aplicación.
- Solicitar consentimiento del administrador.
- Solicitar un token de acceso.
- Llame a Microsoft Graph con el token de acceso.
1. Registro de la aplicación
Antes de que la aplicación pueda usar el punto de conexión de Plataforma de identidad de Microsoft o llamar a Microsoft Graph, debe registrarse correctamente. Siga los pasos para registrar la aplicación en el Centro de administración Microsoft Entra.
En el registro de la aplicación, guarde los valores siguientes:
- Identificador de aplicación (denominado id. de objeto en el Centro de administración Microsoft Entra) asignado por el portal de registro de aplicaciones.
- Un secreto de cliente (contraseña de aplicación), un certificado o una credencial de identidad federada.
- Uri de redireccionamiento para que la aplicación reciba respuestas de token de Microsoft Entra ID.
- Uri de redireccionamiento para que el servicio reciba respuestas de consentimiento del administrador si la aplicación implementa la funcionalidad para solicitar el consentimiento del administrador.
2. Configurar los permisos de Microsoft Graph
Microsoft Graph expone los permisos de aplicación para las aplicaciones que llaman a Microsoft Graph con su propia identidad. Estos permisos siempre requieren el consentimiento del administrador.
Configure previamente los permisos de aplicación que la aplicación necesita al registrar la aplicación. Un administrador puede dar su consentimiento a estos permisos mediante el Centro de administración Microsoft Entra al instalar la aplicación en su organización, o bien puede proporcionar una experiencia de registro en la aplicación a través de la cual los administradores pueden dar su consentimiento a los permisos que ha configurado. Una vez que Microsoft Entra ID registra el consentimiento del administrador, la aplicación puede solicitar tokens sin tener que volver a solicitar el consentimiento.
Para configurar los permisos de aplicación para la aplicación en el portal de registros de aplicaciones de Azure, siga estos pasos:
- En la página Permisos de API de la aplicación, elija Agregar un permiso.
- Seleccione Microsoft Graph.
- Seleccione Permisos de aplicación.
- En el cuadro de diálogo Seleccionar permisos , elija los permisos que se van a configurar en la aplicación.
En la siguiente captura de pantalla se muestra el cuadro de diálogo Seleccionar permisos para los permisos de aplicación de Microsoft Graph.
Importante
Configure siempre el conjunto de permisos con privilegios mínimos que requiere la aplicación. Para obtener más información, consulte Procedimientos recomendados para usar permisos de Microsoft Graph.
3. Solicitar consentimiento del administrador
Los administradores pueden conceder los permisos que la aplicación necesita en el Centro de administración Microsoft Entra. Sin embargo, cuando no tiene acceso a la Centro de administración Microsoft Entra, puede proporcionar una experiencia de registro para los administradores mediante el punto de conexión de Plataforma de identidad de Microsoft/adminconsent.
Importante
Al cambiar los permisos configurados, también debe repetir el proceso de consentimiento del administrador. Los cambios realizados en el portal de registro de aplicaciones no se reflejarán hasta que un administrador autorizado, como un administrador global, vuelva a conectarse a la aplicación.
Solicitud
// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/adminconsent
?client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=https://localhost/myapp/permissions HTTP/1.1
| Parámetro | Condición | Descripción |
|---|---|---|
| tenant | Obligatorio | Inquilino de directorio al que desea solicitar permiso. El valor puede estar en GUID o en un formato de nombre descriptivo. Si no sabe a qué inquilino pertenece el usuario y quiere permitirle iniciar sesión con cualquier inquilino, use common. |
| client_id | Obligatorio | Identificador de aplicación que el portal de registro de aplicaciones de Azure ha asignado a la aplicación. |
| redirect_uri | Obligatorio | Uri de redireccionamiento en el que desea que se envíe la respuesta para que la aplicación la controle. Debe coincidir con uno de los URI de redireccionamiento que registró en el portal. Debe tener codificación URL y puede tener segmentos de ruta de acceso adicionales. |
| state | Recomendado | Valor que se incluye en la solicitud que también se devuelve en la respuesta del token. Puede ser una cadena de cualquier contenido que desee. El estado se usa para codificar 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. |
Experiencia de consentimiento del administrador
Con las solicitudes al /adminconsent punto de conexión, Microsoft Entra ID exige que solo un administrador autorizado pueda iniciar sesión para completar la solicitud. Se pide al administrador que apruebe todos los permisos de aplicación que ha solicitado para la aplicación en el portal de registro de aplicaciones.
La captura de pantalla siguiente es un ejemplo del cuadro de diálogo de consentimiento que Microsoft Entra ID presenta al administrador:
Respuesta
Si el administrador aprueba los permisos de la aplicación, la respuesta correcta tiene un aspecto similar al siguiente:
// Line breaks are for legibility only.
https://localhost/myapp/permissions?admin_consent=True&tenant=38d49456-54d4-455d-a8d6-c383c71e0a6d&state=12345#
| Parámetro | Descripción |
|---|---|
| tenant | Inquilino de directorio que ha concedido a la aplicación los permisos que ha solicitado, en formato GUID. |
| state | Valor que se incluye en la solicitud que también se devuelve en la respuesta del token. Puede ser una cadena de cualquier contenido que desee. El estado se usa para codificar 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. |
| admin_consent | Establézcalo en True. |
4. Solicitud de un token de acceso
En el flujo de concesión de credenciales de cliente de OAuth 2.0 se usan los valores del id. de aplicación y el secreto de cliente que se guardaron al registrar la aplicación para solicitar un token de acceso directamente desde el punto de conexión /token de la plataforma de identidad de Microsoft.
Especifique los permisos preconfigurados pasando https://graph.microsoft.com/.default como valor para el scope parámetro en la solicitud de token.
Solicitud de token
Envíe una solicitud POST al punto de conexión de la /token plataforma de identidad para adquirir un token de acceso. En esta solicitud, el cliente usa el secreto de cliente.
// Line breaks are for legibility only.
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Parámetro | Condición | Descripción |
|---|---|---|
| tenant | Obligatorio | Inquilino de directorio al que desea solicitar permiso. El valor puede estar en GUID o en un formato de nombre descriptivo. |
| client_id | Obligatorio | Identificador de aplicación que el portal de registro de aplicaciones de Azure ha asignado al registrar la aplicación. |
| ámbito | Obligatorio | El valor pasado para el parámetro scope en esta solicitud debe ser el identificador (URI del identificador de aplicación) del recurso que le interesa, con el sufijo .default anexado. Por ejemplo, el URI de identificador de la aplicación de recursos de Microsoft Graph es https://graph.microsoft.com/. Por lo tanto, para Microsoft Graph, el valor de scope es https://graph.microsoft.com/.default. Este valor informa al punto de conexión de la plataforma de identidad de Microsoft para incluir en el token de acceso todos los permisos de nivel de aplicación a los que el administrador ha dado su consentimiento. |
| client_secret | Obligatorio | Secreto de cliente que generó para la aplicación en el portal de registro de aplicaciones. Asegúrese de que su dirección URL esté codificada. |
| grant_type | Obligatorio | Debe ser client_credentials. |
Respuesta de token
Una respuesta correcta tiene un aspecto similar al siguiente:
{
"token_type": "Bearer",
"expires_in": 3599,
"ext_expires_in":3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBP..."
}
| Parámetro | Descripción |
|---|---|
| access_token | El token de acceso solicitado. La aplicación puede usar este token en llamadas a Microsoft Graph. |
| expires_in | Período de validez del token de acceso (en segundos). |
| ext_expires_in | Se usa para indicar una duración extendida del token de acceso y para admitir resistencia cuando el servicio de emisión de tokens no responde. |
| token_type | Indica el valor del tipo de token. El único tipo que Microsoft Entra ID admite es Bearer. |
5. Usar el token de acceso para llamar a Microsoft Graph
Después de tener un token de acceso, la aplicación lo usa para llamar a Microsoft Graph adjuntando el token de acceso como token de portador al encabezado Authorization en una solicitud HTTP. La siguiente solicitud obtiene todos los usuarios del inquilino. La aplicación debe tener el permiso User.Read.All para llamar a esta API.
GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com
Una respuesta correcta tiene este aspecto (se han quitado algunos encabezados de respuesta):
HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Date: Wed, 26 Apr 2017 19:53:49 GMT
Content-Length: 407
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
"value": [
{
"businessPhones": [],
"displayName": "Conf Room Adams",
"givenName": null,
"jobTitle": null,
"mail": "Adams@Contoso.com",
"mobilePhone": null,
"officeLocation": null,
"preferredLanguage": null,
"surname": null,
"userPrincipalName": "Adams@Contoso.com",
"id": "8afc02cb-4d62-4dba-b536-9f6d73e9be26"
},
{
"businessPhones": [
"+1 425 555 0109"
],
"displayName": "Adele Vance",
"givenName": "Adele",
"jobTitle": "Retail Manager",
"mail": "AdeleV@Contoso.com",
"mobilePhone": null,
"officeLocation": "18/2111",
"preferredLanguage": null,
"surname": "Vance",
"userPrincipalName": "AdeleV@Contoso.com",
"id": "59bb3898-0621-4414-ac61-74f9d7201355"
}
]
}
Escenarios de aplicación admitidos y recursos
Las aplicaciones que realizan llamadas a Microsoft Graph con su propia identidad están en una de las dos categorías siguientes:
- Servicios en segundo plano (demonios) que se ejecutan en un servidor sin que un usuario inicie la sesión.
- Aplicaciones que tienen un usuario que ha iniciado sesión, pero que también llaman a Microsoft Graph con su propia identidad. Por ejemplo, para usar la funcionalidad que requiere más privilegios elevados de los que tiene el usuario.
En este artículo, la aplicación usó un secreto de cliente como credencial. Opcionalmente, puede configurar un certificado o una credencial de identidad federada.
Para obtener más información sobre las aplicaciones que llaman a Microsoft Graph con su propia identidad y usan el flujo de credenciales de cliente, consulte Flujos de autenticación y escenarios de aplicación: Aplicación de demonio que llama a una API web en el nombre del demonio.
Uso de la biblioteca de autenticación de Microsoft (MSAL)
En este artículo, ha recorrido los detalles del protocolo de bajo nivel que normalmente solo se requieren al crear y emitir manualmente solicitudes HTTP sin procesar para ejecutar el flujo de credenciales de cliente. En las aplicaciones de producción, use una biblioteca de autenticación compatible o compilada por Microsoft, como la Biblioteca de autenticación de Microsoft (MSAL), para obtener tokens de seguridad y llamar a API web protegidas como Microsoft Graph.
MSAL y otras bibliotecas de autenticación admitidas simplifican el proceso mediante el control de detalles como la validación, el control de cookies, el almacenamiento en caché de tokens y las conexiones seguras, lo que le permite centrarse en la funcionalidad de la aplicación.
Microsoft ha creado y mantiene una amplia selección de ejemplos de código que muestran el uso de bibliotecas de autenticación admitidas con el Plataforma de identidad de Microsoft. Para acceder a estos ejemplos de código, consulte los ejemplos de código de Plataforma de identidad de Microsoft.
Contenido relacionado
- Elija entre ejemplos de código creados y mantenidos por Microsoft para ejecutar aplicaciones personalizadas que usen bibliotecas de autenticación admitidas, usuarios de inicio de sesión y llamadas a Microsoft Graph. Consulte tutoriales de Microsoft Graph.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de