Administración de métodos de autenticación de usuarios mediante Microsoft Graph
Artículo
Los métodos de autenticación son las maneras en que los usuarios se autentican en Microsoft Entra ID. Los siguientes métodos de autenticación están disponibles en Microsoft Entra ID hoy en día y se pueden administrar a través de Microsoft Graph:
Windows Hello para empresas
Microsoft Authenticator
Clave de seguridad FIDO2
Autenticación basada en certificados
Tokens de hardware OATH (versión preliminar)
Tokens de software OATH
Pase de acceso temporal (TAP)
SMS
Voz
Password
Los métodos de autenticación se usan en la autenticación principal, de segundo factor y de nivel superior, y también en el proceso de restablecimiento de contraseña de autoservicio (SSPR).
¿Qué puede hacer con las API de métodos de autenticación?
Puede usar las API de método de autenticación para integrarlas en las aplicaciones para administrar los métodos de autenticación de un usuario. Por ejemplo, puede:
Agregar un número de teléfono para un usuario que, a su vez, puede usarlo para autenticarse por SMS y llamada de voz, en caso de que la directiva habilite su uso
Actualizar o eliminar el número de teléfono asignado a un usuario
Habilitar o deshabilitar el número para iniciar sesión de SMS
Restablecer la contraseña de un usuario
Importante
No se recomienda usar las API de métodos de autenticación para escenarios en los que tenga que recorrer en iteración toda la población de usuarios con fines de auditoría o comprobación de seguridad. Para estos tipos de escenarios, se recomienda usar el registro del método de autenticación y las API de informes de uso (algunas API solo están disponibles en el punto de beta conexión).
Uso de directivas para administrar métodos de autenticación en el inquilino
Puede elegir qué métodos de autenticación se permiten para los usuarios del inquilino mediante la configuración de directivas de método de autenticación. Para cada directiva, configure si el método de autenticación está habilitado, su configuración y puede definir explícitamente los grupos de usuarios a los que se permite o no usar el método.
Ejemplo ficticio
En este artículo, aprenderá a:
Autenticación para Microsoft Entra ID con los roles y permisos adecuados
Comprobar los métodos de autenticación del usuario
Agregar números de teléfono nuevos para el usuario
Quitar un número de teléfono del usuario
Restablecer la contraseña del usuario
Paso 1: Autenticación para Microsoft Entra ID con los roles y permisos adecuados
Inicie sesión en un cliente de API, como Graph Explorer, con una cuenta que tenga al menos el rol Administrador de autenticación con privilegios o Administradorde autenticación Microsoft Entra. Puede usar un inquilino de prueba con datos de ejemplo para probar las API.
A continuación, conceda a la aplicación el permiso UserAuthenticationMethod.ReadWrite.All . Necesita este permiso para realizar las operaciones de lectura y escritura en este escenario.
Ahora puede empezar a usar las API. En este escenario, usará las API para administrar los métodos de autenticación de Cameron White.
Paso 2: Comprobar los métodos de autenticación del usuario
GET https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/methods
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Methods.GetAsync();
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
AuthenticationMethodCollectionResponse result = graphClient.users().byUserId("{user-id}").authentication().methods().get();
A partir de esta respuesta, Cameron solo tiene habilitado el método de autenticación de contraseña. 28c10230-6103-485e-b985-444c60001490es el identificador único global del método de autenticación de contraseña en Microsoft Entra ID.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('CameronW%40contoso.com')/authentication/methods",
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<key>')/authentication/methods?$select=id",
"value": [
{
"@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
"id": "28c10230-6103-485e-b985-444c60001490",
"password": null,
"createdDateTime": "2023-09-18T10:38:07Z"
}
]
}
Paso 3: Agregar números de teléfono nuevos para el usuario
En este paso, agregará un nuevo número de teléfono móvil para que Cameron lo use.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new PhoneAuthenticationMethod
{
PhoneNumber = "+1 2065555555",
PhoneType = AuthenticationPhoneType.Mobile,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.PhoneMethods.PostAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users authentication phone-methods create --user-id {user-id} --body '{\
"phoneNumber": "+1 2065555555",\
"phoneType": "mobile"\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
PhoneAuthenticationMethod phoneAuthenticationMethod = new PhoneAuthenticationMethod();
phoneAuthenticationMethod.setPhoneNumber("+1 2065555555");
phoneAuthenticationMethod.setPhoneType(AuthenticationPhoneType.Mobile);
PhoneAuthenticationMethod result = graphClient.users().byUserId("{user-id}").authentication().phoneMethods().post(phoneAuthenticationMethod);
GET https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/methods
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Methods.GetAsync();
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
AuthenticationMethodCollectionResponse result = graphClient.users().byUserId("{user-id}").authentication().methods().get();
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('CameronW%40contoso.com')/authentication/methods",
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<key>')/authentication/methods?$select=id",
"value": [
{
"@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
"id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
"phoneNumber": "+1 4255550199",
"phoneType": "office",
"smsSignInState": "notSupported"
},
{
"@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
"id": "3179e48a-750b-4051-897c-87b9720928f7",
"phoneNumber": "+1 2065555555",
"phoneType": "mobile",
"smsSignInState": "notAllowedByPolicy"
},
{
"@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
"id": "28c10230-6103-485e-b985-444c60001490",
"password": null,
"createdDateTime": "2023-09-18T10:38:07Z"
}
]
}
Confirme que puede ver ambos números como esperaba. Los identificadores de los diferentes tipos de números de teléfono son globalmente los mismos en Microsoft Entra ID como se indica a continuación:
b6332ec1-7057-4abe-9331-3d72feddfe41para el tipo de teléfono alternateMobile
e37fc753-ff3b-4958-9484-eaa9425c82bcpara el tipo de teléfono de la oficina
3179e48a-750b-4051-897c-87b9720928f7para el tipo de teléfono móvil
Paso 5: Quitar un número de teléfono del usuario
Cameron está trabajando desde casa, por lo que debe quitar el número de oficina de su cuenta.
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Users["{user-id}"].Authentication.PhoneMethods["{phoneAuthenticationMethod-id}"].DeleteAsync();
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users authentication phone-methods delete --user-id {user-id} --phone-authentication-method-id {phoneAuthenticationMethod-id}
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.users().byUserId("{user-id}").authentication().phoneMethods().byPhoneAuthenticationMethodId("{phoneAuthenticationMethod-id}").delete();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->users()->byUserId('user-id')->authentication()->phoneMethods()->byPhoneAuthenticationMethodId('phoneAuthenticationMethod-id')->delete()->wait();
La solicitud devuelve un código de respuesta 204 No Content. Para comprobar que el método de teléfono de la oficina se quitó de la cuenta de Cameron, vuelva a ejecutar la solicitud en el paso 4. Cameron debería tener ahora solo los métodos de autenticación de teléfono móvil y contraseña.
Paso 6: Restablecer la contraseña del usuario
Cameron ha olvidado su contraseña y usted necesita restablecerla para ellos. Puede restablecer la contraseña de un usuario y especificar una contraseña temporal, o puede permitir que Microsoft Entra ID genere una contraseña temporal.
En ambos métodos, la respuesta incluye un encabezado Location con una dirección URL que puede usar para comprobar el estado de la operación a través de una operación GET. La operación de restablecimiento no se completa inmediatamente, ya que Microsoft Entra ID necesita sincronizar la contraseña, incluida la de Active Directory en la infraestructura local del inquilino (para usuarios locales). La dirección URL es válida durante 24 horas.
Opción 1: Restablecer la contraseña del usuario y proporcionar una nueva contraseña temporal
GET https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/operations/ba0c9a11-5163-4353-89ba-81501617ede0?aadgdc=AM4P&aadgsu=ssprprod-a
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Operations["{longRunningOperation-id}"].GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Aadgdc = "AM4P";
requestConfiguration.QueryParameters.Aadgsu = "ssprprod-a";
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users authentication operations get --user-id {user-id} --long-running-operation-id {longRunningOperation-id}
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
LongRunningOperation result = graphClient.users().byUserId("{user-id}").authentication().operations().byLongRunningOperationId("{longRunningOperation-id}").get(requestConfiguration -> {
requestConfiguration.queryParameters.aadgdc = "AM4P";
requestConfiguration.queryParameters.aadgsu = "ssprprod-a";
});
HTTP/1.1 202 Accepted
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('a87cc624-b550-4559-b934-3bc0325a4808')/authentication/operations/$entity",
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<guid>')/authentication/operations('<guid>')?$select=createdDateTime,lastActionDateTime",
"id": "ba0c9a11-5163-4353-89ba-81501617ede0",
"createdDateTime": "2024-01-18T16:37:10Z",
"lastActionDateTime": "2024-01-18T16:37:10Z",
"status": "succeeded",
"statusDetail": "ResetSuccess",
"resourceLocation": "https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/methods/28c10230-6103-485e-b985-444c60001490"
}
Referencia de la API
¿Busca la referencia de la API para métodos de autenticación?
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.