Introducción a la API de métodos de autenticación de Microsoft Graph

Los métodos de autenticación son las formas en que los usuarios se autentican en Azure Active Directory (Azure AD). Los métodos de autenticación de Azure AD incluyen contraseña y teléfono (por ejemplo, llamadas de voz y SMS), que son hoy fáciles de administrar en Microsoft Graph, además de otros como las claves de seguridad FIDO2 y la aplicación Microsoft Authenticator. 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).

Puede usar las API del método de autenticación 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

Las API son una herramienta clave para administrar los métodos de autenticación de los usuarios.

En este tutorial, aprenderá a:

  • Autenticar a Azure AD con las funciones 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: Autenticar a Azure AD con las funciones y permisos adecuados

Con su herramienta favorita para interactuar con Microsoft Graph, inicie sesión con una cuenta que tenga uno de estos roles:

  • Administrador global
  • Administrador de autenticación con privilegios
  • Administrador de autenticación

Después, modifique los permisos. Usaremos UserAuthenticationMethod.ReadWrite.All en este tutorial, así que asegúrese de que está habilitado en el Probador de Graph o en la aplicación.

Una vez que el ámbito se haya asignado y aceptado, puede empezar a usar la API. Estos ejemplos usan un usuario estándar denominado Avery Howard. Debe usar una cuenta de prueba existente o crear una nueva siguiendo estas instrucciones. Estas API están ya activas, por lo tanto, no las pruebe en usuarios reales.

Paso 2: Comprobar los métodos de autenticación del usuario

Haga una llamada para ver los métodos de autenticación del usuario Tome la dirección URL para ver el perfil de un usuario y agregue /authentication/methods:

Solicitud

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/methods

Respuesta

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/methods",
    "value": [
        {
            "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
            "id": "28c10230-6103-485e-b985-444c60001490",
            "password": null,
            "creationDateTime": null
        }
    ]
}

Paso 3: Agregar números de teléfono nuevos para el usuario

En el paso anterior, un nuevo usuario (Avery) solo tiene una contraseña registrada. Para asignar un número de teléfono nuevo que pueda usar Avery, haga una solicitud POST con el tipo de teléfono y el número en el cuerpo de la solicitud. Para indicar al sistema que se va a agregar un número de teléfono, también tendrá que cambiar el final de la dirección URL de methods a phoneMethods.

Solicitud

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods
Content-Type: application/json
{
    "phoneType": "mobile",
    "phoneNumber": "+1 2065550123"
}

Respuesta

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods/$entity",
    "id": "3179e48a-750b-4051-897c-87b9720928f7",
    "phoneNumber": "+1 2065550123",
    "phoneType": "mobile",
    "smsSignInState": "ready"
}

Para agregar el número de la oficina de Avery, vuelva a hacer una solicitud POST a la misma dirección URL, pero con el tipo y el número de teléfono actualizados:

Solicitud

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods
Content-Type: application/json
{
    "phoneType": "office",
    "phoneNumber": "+1 4255550199"
}

Respuesta

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods/$entity",
    "id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
    "phoneNumber": "+1 4255550199",
    "phoneType": "office",
    "smsSignInState": "notSupported"
}

Realice una nueva solicitud GET a la dirección URL de los métodos telefónicos para ver todos los números de teléfono de Avery:

Solicitud

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods

Respuesta

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods",
    "value": [
        {
            "id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
            "phoneNumber": "+1 4255550199",
            "phoneType": "office",
            "smsSignInState": "notSupported"
        },
        {
            "id": "3179e48a-750b-4051-897c-87b9720928f7",
            "phoneNumber": "+1 2065550123",
            "phoneType": "mobile",
            "smsSignInState": "ready"
        }
    ]
}

Confirme que puede ver ambos números como esperaba.

Paso 4: Quitar un número de teléfono del usuario

En este escenario, Avery está trabajando desde casa y usted debe quitar de su cuenta el número de la oficina. Haga una solicitud DELETE a la dirección URL de la oficina telefónica, que puede crear anexando el id. de teléfono de la oficina a la dirección URL de los métodos telefónicos. Eche un vistazo a la lista de teléfonos de Avery: el id. de teléfono de la oficina empieza por "e37f".

Solicitud

DELETE https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods/e37fc753-ff3b-4958-9484-eaa9425c82bc

No hay ningún dato en la respuesta, ya que —como pretendíamos— el teléfono de oficina ya no está presente. Para confirmar que ha desaparecido, eche un vistazo a todos los métodos de Avery. Esto se puede realizar con la misma solicitud GET que hizo antes:

Solicitud

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/methods

Respuesta

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/methods",
    "value": [
        {
            "@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
            "id": "3179e48a-750b-4051-897c-87b9720928f7",
            "phoneNumber": "+1 2065550123",
            "phoneType": "mobile",
            "smsSignInState": "ready"
        },
        {
            "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
            "id": "28c10230-6103-485e-b985-444c60001490",
            "password": null,
            "creationDateTime": null
        }
    ]
}

Como se esperaba, el usuario ahora vuelve a tener solo un teléfono móvil y una contraseña.

Paso 5: Restablecer la contraseña del usuario

En este escenario, Avery ha olvidado la contraseña y necesita restablecerla. Para restablecerla, realice una solicitud POST a la dirección URL de su contraseña (consulte la id. que comienza por "28c1" más arriba en la lista de métodos de autenticación de Avery), especificando la acción "resetPassword". Proporcione la nueva contraseña en el cuerpo de la solicitud.

Solicitud

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/passwordMethods/28c10230-6103-485e-b985-444c60001490/resetPassword
Content-Type: application/json
{
    "newPassword": "29sdjfw#fajsdA_a_3an3223"
}

Respuesta

Location: https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/operations/74bfa1a6-c0e0-4957-8c37-f91048f4959e?aadgdc=BY01P&aadgsu=ssprprod-a

Debido a que este proceso sincroniza la contraseña en Active Directory en la infraestructura local del espacio empresarial, puede tardar unos minutos. Para comprobar cuándo se ha completado, tiene disponible una dirección. Esta dirección se encuentra en el encabezado de ubicación de la respuesta y para ver su estado solo tiene que realizar una solicitud GET a esa dirección URL.

Solicitud

GET https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/operations/74bfa1a6-c0e0-4957-8c37-f91048f4959e?aadgdc=BY01P&aadgsu=ssprprod-a

Respuesta

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('ed178e23-7447-4892-baf8-fc46f8af26ce')/authentication/operations/$entity",
    "id": "74bfa1a6-c0e0-4957-8c37-f91048f4959e",
    "createdDateTime": "2020-05-14T00:23:40Z",
    "lastActionDateTime": "2020-05-14T00:23:41Z",
    "status": "succeeded",
    "statusDetail": "ResetSuccess",
    "resourceLocation": "https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/methods/28c10230-6103-485e-b985-444c60001490"
}

¡Misión cumplida! Ya ha visto el perfil de un usuario, sus métodos de autenticación, cómo agregar y quitar números de teléfono y cómo restablecer la contraseña. Ya está listo para administrar los métodos de los usuarios.

Referencia de la API

¿Busca la referencia de la API para métodos de autenticación?

Pasos siguientes