Introducción a la API de métodos de autenticación de Microsoft GraphGet started with the Microsoft Graph authentication methods API

Los métodos de autenticación son las formas en que los usuarios se autentican en Azure Active Directory (Azure AD).Authentication methods are the ways that users authenticate in 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.Authentication methods in Azure AD include password and phone (for example, SMS and voice calls), which are manageable in Microsoft Graph today, among many others such as FIDO2 security keys and the Microsoft Authenticator app. 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).Authentication methods are used in primary, second-factor, and step-up authentication, and also in the self-service password reset (SSPR) process.

Puede usar las API del método de autenticación para administrar los métodos de autenticación de un usuario.You can use the authentication method APIs to manage a user's authentication methods. Por ejemplo, puede:For example, you can:

  • 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 usoAdd a phone number for a user, who can then use that number for SMS and voice call authentication if they're enabled to use it by policy
  • Actualizar o eliminar el número de teléfono asignado a un usuarioUpdate or delete the phone number assigned to a user
  • Habilitar o deshabilitar el número para iniciar sesión de SMSEnable or disable the number for SMS sign-in
  • Restablecer la contraseña de un usuarioReset a user's password

Las API son una herramienta clave para administrar los métodos de autenticación de los usuarios.The APIs are a key tool to manage your users' authentication methods.

En este tutorial, aprenderá a:In this tutorial, you'll learn how to:

  • Autenticar a Azure AD con las funciones y permisos adecuadosAuthenticate to Azure AD with the right roles and permissions
  • Comprobar los métodos de autenticación del usuarioCheck the user's authentication methods
  • Agregar números de teléfono nuevos para el usuarioAdd new phone numbers for the user
  • Quitar un número de teléfono del usuarioRemove a phone number from the user
  • Restablecer la contraseña del usuarioReset the user's password

Paso 1: Autenticar a Azure AD con las funciones y permisos adecuadosStep 1: Authenticate to Azure AD with the right roles and permissions

Con su herramienta favorita para interactuar con Microsoft Graph, inicie sesión con una cuenta que tenga uno de estos roles:Using your favorite tool for interacting with Microsoft Graph, sign in using an account with one of these roles:

  • Administrador globalGlobal administrator
  • Administrador de autenticación con privilegiosPrivileged authentication administrator
  • Administrador de autenticaciónAuthentication administrator

Después, modifique los permisos.Next, modify your permissions. 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.We'll use UserAuthenticationMethod.ReadWrite.All for this tutorial, so make sure it's enabled in Graph Explorer or your app.

Una vez que el ámbito se haya asignado y aceptado, puede empezar a usar la API.Once the scope is assigned and consented, you can start using the API. Estos ejemplos usan un usuario estándar denominado Avery Howard.The examples here use a standard user named Avery Howard. Debe usar una cuenta de prueba existente o crear una nueva siguiendo estas instrucciones.You should use a preexisting test account or create a new one following these instructions. Estas API están ya activas, por lo tanto, no las pruebe en usuarios reales.These APIs are live so don't test them on real users.

Paso 2: Comprobar los métodos de autenticación del usuarioStep 2: Check the user's authentication methods

Haga una llamada para ver los métodos de autenticación del usuarioMake a call to see the user's authentication methods. Tome la dirección URL para ver el perfil de un usuario y agregue /authentication/methods:Take the URL to see a user's profile and add /authentication/methods:

SolicitudRequest

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

RespuestaResponse

{
    "@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 usuarioStep 3: Add new phone numbers for the user

En el paso anterior, un nuevo usuario (Avery) solo tiene una contraseña registrada.From the previous step, a new user (Avery) only has a password registered. 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.To assign a new phone number for Avery to use, make a POST request with the phone type and number in the body. 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.To tell the system that a phone number is being added, you'll also need to change the end of the URL from methods to phoneMethods.

SolicitudRequest

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

RespuestaResponse

{
    "@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:To add Avery's office number, you'll POST again to the same URL but update the phone type and number:

SolicitudRequest

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

RespuestaResponse

{
    "@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:Do one more GET to the phone methods URL to see all of Avery's phone numbers:

SolicitudRequest

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

RespuestaResponse

{
    "@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.Confirm that you can see both numbers as expected.

Paso 4: Quitar un número de teléfono del usuarioStep 4: Remove a phone number from the user

En este escenario, Avery está trabajando desde casa y usted debe quitar de su cuenta el número de la oficina.In this scenario, Avery is now working from home you need to remove their office number from their account. 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.You need to call DELETE on the office phone URL, which you can create by appending the office phone's ID to the phone methods URL. Eche un vistazo a la lista de teléfonos de Avery: el id. de teléfono de la oficina empieza por "e37f".Look at Avery's list of phones above: the office phone ID starts with "e37f".

SolicitudRequest

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.There's no data in the response because there's no more office phone as intended. 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:You can confirm it's gone by looking at all of Avery's methods, which is the same GET that was made previously:

SolicitudRequest

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

RespuestaResponse

{
    "@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.As expected, the user is now back to only having one mobile phone and a password.

Paso 5: Restablecer la contraseña del usuarioStep 5: Reset the user's password

En este escenario, Avery ha olvidado la contraseña y necesita restablecerla.In this scenario, Avery has forgotten their password and you need to reset it for them. 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".To reset, you'll make a POST to their password's URL (see the ID starting with "28c1" above in Avery's list of authentication methods), specifying the "resetPassword" action. Proporcione la nueva contraseña en el cuerpo de la solicitud.Provide the new password in the request body.

SolicitudRequest

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"
}

RespuestaResponse

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.Because this is syncing the password down to Active Directory in the tenant's on-prem infrastructure, it might take a few minutes, so you have an address where you can check to see if it's complete. 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.This address is in the location header of the response, and to see the status do a GET on that URL.

SolicitudRequest

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

RespuestaResponse

{
    "@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!And success! 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.You've walked through seeing a user's profile, their auth methods, adding and removing phone numbers, and resetting their password. Ya está listo para administrar los métodos de los usuarios.Now you're ready to go manage your own users' methods.

Referencia de la APIAPI reference

¿Busca la referencia de la API para métodos de autenticación?Looking for the API reference for authentication methods?

Pasos siguientesNext steps