Inicio rápido: Llamada a una API web protegida por la plataforma de identidad de Microsoft

Se aplica a: Inquilinos del personal Inquilinos externos (más información)

En este inicio rápido, usará una aplicación web de ejemplo para mostrar cómo proteger una API web de ASP.NET mediante la plataforma de identidad de Microsoft. En el ejemplo se usa la Biblioteca de autenticación de Microsoft (MSAL) para controlar la autenticación y la autorización.

Prerrequisitos

• Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
• Registre una nueva aplicación en el Centro de administración de Microsoft Entra y registre sus identificadores en la página Información general de la aplicación. Para obtener más información, consulte Registro de una aplicación.
  • Nombre: NewWebAPI1
  • Tipos de cuenta admitidos: solo las cuentas de este directorio organizativo (inquilino único)

ASP.NET

• Visual Studio 2022. Descargue Visual Studio de forma gratuita.

ASP.NET Core

• Visual Studio Code

Exponer la API

Una vez registrada la API, puedes configurar tu permiso definiendo los ámbitos que expone la API a las aplicaciones cliente. Las aplicaciones cliente solicitan permiso para realizar operaciones mediante el paso de un token de acceso junto con sus solicitudes a la API web protegida. Luego, la API web realiza la operación solicitada solo si el token de acceso que recibe contiene los ámbitos requeridos.

ASP.NET

1. En Administrar, seleccione Exponer una API>Agregar un ámbito. Acepte el URI de id. de aplicación propuesto (api://{clientId}) seleccionando Guardar y continuar y, a continuación, escriba la siguiente información:

   1. En Nombre de ámbito, escriba access_as_user.
   2. En Who can consent (Quién puede dar su consentimiento), asegúrese de que la opción Admins and users (Administradores y usuarios ) está seleccionada.
   3. En el cuadro Nombre para mostrar del consentimiento del administrador, escriba Access TodoListService as a user.
   4. En el cuadro Descripción del consentimiento del administrador , escriba Accesses the TodoListService web API as a user.
   5. En el cuadro Nombre para mostrar consentimiento del usuario , escriba Access TodoListService as a user.
   6. En el cuadro Descripción del consentimiento del usuario , escriba Accesses the TodoListService web API as a user.
   7. En Estado, mantenga Habilitado.

2. Seleccione Agregar ámbito.

ASP.NET Core

Agregar permisos delegados (ámbitos)

Una API debe publicar un mínimo de un ámbito, también denominado Permiso delegado, para que las aplicaciones cliente obtengan un token de acceso para un usuario correctamente. Para publicar un ámbito, siga estos pasos:

1. En la página Registros de aplicaciones, seleccione la aplicación de API que creó (ciam-ToDoList-api) para abrir su página información general .

2. En Administrar, seleccione Exponer una API.

3. En la parte superior de la página, junto a URI de id. de aplicación, seleccione el vínculo Agregar para generar un URI único para esta aplicación.

4. Acepte el identificador URI del ID de aplicación propuesto, como api://{clientId}, y seleccione Guardar. Cuando la aplicación web solicite un token de acceso para la API web, deberá agregar este URI como prefijo para cada ámbito que se defina para la API.

5. En Ámbitos definidos por esta API, seleccione Agregar un ámbito.

6. Escriba los siguientes valores que definen un acceso de lectura a la API y seleccione Agregar ámbito para guardar los cambios:

   Propiedad	Valor
   Nombre de ámbito	ToDoList.Leer
   ¿Quién puede dar el consentimiento?	Solo administradores
   Nombre para mostrar del consentimiento del administrador	Leer la lista ToDo de usuarios mediante "TodoListApi"
   Descripción del consentimiento del administrador	Permitir que la aplicación lea la lista ToDo del usuario mediante "TodoListApi".
   Estado	Habilitado

7. Seleccione Agregar un ámbito de nuevo y escriba los siguientes valores que definen un ámbito de acceso de lectura y escritura a la API. Seleccione Agregar ámbito para guardar los cambios:

   Propiedad	Valor
   Nombre de ámbito	ToDoList.ReadWrite
   ¿Quién puede dar el consentimiento?	Solo administradores
   Nombre para mostrar del consentimiento del administrador	Leer y escribir la lista de tareas de los usuarios mediante "ToDoListApi"
   Descripción del consentimiento del administrador	Permitir que la aplicación lea y escriba la lista ToDo del usuario mediante "ToDoListApi"
   Estado	Habilitado

Obtenga más información sobre el principio de privilegios mínimos al publicar permisos para una API web.

Agregar permisos de aplicación (roles de app)

Una API debe publicar un mínimo de un rol de aplicación para las aplicaciones, también denominado Permiso de aplicación, para que las aplicaciones cliente obtengan un token de acceso como ellos mismos. Los permisos de aplicación son el tipo de permisos que las API deben publicar cuando quieran permitir que las aplicaciones cliente se autentiquen correctamente como ellas mismas y no necesiten registrar a los usuarios. Para publicar un permiso de aplicación, siga estos pasos:

1. En la página Registros de aplicaciones, seleccione la aplicación que creó (por ejemplo , ciam-ToDoList-api) para abrir su página Información general .

2. En Administrar, seleccione Roles de aplicación.

3. Seleccione Crear rol de aplicación y, a continuación, escriba los valores siguientes y, después, seleccione Aplicar para guardar los cambios:

   Propiedad	Valor
   Nombre para mostrar	ToDoList.Read.All
   Tipos de miembros permitido	Aplicaciones
   Valor	ToDoList.Read.All
   Descripción	Permitir que la aplicación lea la lista ToDo de todos los usuarios mediante "TodoListApi".
   ¿Quiere habilitar este rol de aplicación?	Mantenerla activada

4. Vuelva a seleccionar Crear rol de aplicación y, a continuación, escriba los valores siguientes para el segundo rol de aplicación y, después, seleccione Aplicar para guardar los cambios:

   Propiedad	Valor
   Nombre para mostrar	ToDoList.ReadWrite.All
   Tipos de miembros permitido	Aplicaciones
   Valor	ToDoList.ReadWrite.All
   Descripción	Permitir que la aplicación lea y escriba la lista ToDo de todos los usuarios mediante "ToDoListApi".
   ¿Quiere habilitar este rol de aplicación?	Mantenerla activada

Clonar o descargar la aplicación de ejemplo

Para obtener la aplicación de ejemplo, puede clonarla desde GitHub o descargarla como un archivo .zip .

ASP.NET

git clone https://github.com/AzureADQuickStarts/AppModelv2-NativeClient-DotNet.git

• Descárguelo como un archivo ZIP.

Sugerencia

Para evitar errores causados por limitaciones de longitud de ruta de acceso en Windows, se recomienda extraer el archivo o clonar el repositorio en un directorio cerca de la raíz de la unidad.

ASP.NET Core

git clone https://github.com/Azure-Samples/ms-identity-ciam-dotnet-tutorial.git

• Descargue el archivo .zip. Extráigalo en una ruta de acceso de archivo donde la longitud del nombre sea inferior a 260 caracteres.

Configurar la aplicación de ejemplo

Configure el ejemplo de código para que coincida con la API web registrada.

ASP.NET

1. Abra la solución en Visual Studio y, a continuación, abra el archivo appsettings.json en la raíz del proyecto TodoListService.

2. Reemplace el valor de Enter_the_Application_Id_here por el valor de la Identificación de Cliente (Id. de aplicación) de la aplicación que registró en el portal de Registros de Aplicaciones, tanto en las propiedades de ClientID como en las de Audience.

Agregue el nuevo ámbito al archivo app.config

Para agregar el nuevo ámbito al archivo app.config TodoListClient, siga estos pasos:

1. En la carpeta raíz del proyecto TodoListClient, abra el archivo app.config .

2. Pegue el identificador de la aplicación que acaba de registrar para el proyecto TodoListService en el parámetro TodoListServiceScope y reemplace la cadena {Enter the Application ID of your TodoListService from the app registration portal}.

Nota:

Asegúrese de que el identificador de aplicación usa el siguiente formato: api://{TodoListService-Application-ID}/access_as_user (donde {TodoListService-Application-ID} es el GUID que representa el identificador de aplicación de la aplicación TodoListService).

Registrar la aplicación web (TodoListClient)

Registre la aplicación TodoListClient en Registros de aplicaciones en el Centro de administración de Microsoft Entra y, a continuación, configure el código en el proyecto TodoListClient. Si el cliente y el servidor se consideran la misma aplicación, puede reutilizar la aplicación registrada en el paso 2. Use la misma aplicación si desea que los usuarios inicien sesión con una cuenta microsoft personal.

Registro de la aplicación

Para registrar la aplicación TodoListClient, siga estos pasos:

1. Inicie sesión en el Centro de administración de Microsoft Entra como al menos un administrador de aplicaciones en la nube.

2. Vaya a Entra ID>Registros de Aplicaciones y seleccione Nuevo registro.

3. Seleccione Nuevo registro.

4. Cuando se abra la página Registrar una aplicación , escriba la información de registro de la aplicación:

   1. En la sección Nombre , escriba un nombre de aplicación significativo que se mostrará a los usuarios de la aplicación (por ejemplo, NativeClient-DotNet-TodoListClient).
   2. En Tipos de cuenta admitidos, seleccione Cuentas en cualquier directorio organizativo.
   3. Seleccione Registrar para crear la aplicación.

   Nota:

   En el archivo app.config proyecto TodoListClient, el valor predeterminado de ida:Tenant se establece en common. Los valores posibles son:

   • common: puede iniciar sesión con una cuenta profesional o educativa o una cuenta microsoft personal (ya que seleccionó Cuentas en cualquier directorio organizativo en un paso anterior).
   • organizations: puede iniciar sesión con una cuenta profesional o educativa.
   • consumers: solo puede iniciar sesión con una cuenta personal de Microsoft.

5. En la página Información general de la aplicación, seleccione Autenticación y, a continuación, complete estos pasos para agregar una plataforma:

   1. En Configuraciones de plataforma, seleccione el botón Agregar una plataforma .
   2. En Aplicaciones móviles y de escritorio, seleccione Aplicaciones móviles y de escritorio.
   3. En URI de redirección, active la casilla de verificación https://login.microsoftonline.com/common/oauth2/nativeclient.
   4. Seleccione Configurar.

6. Seleccione Permisos de API y, a continuación, complete estos pasos para agregar permisos:

   1. Seleccione el botón Agregar un permiso .
   2. Seleccione la pestaña Mis API .
   3. En la lista de API, seleccione AppModelv2-NativeClient-DotNet-TodoListService API o el nombre especificado para la API web.
   4. Seleccione la casilla de permiso access_as_user si aún no está seleccionada. Use el cuadro Buscar si es necesario.
   5. Seleccione el botón Agregar permisos .

Configuración del proyecto

Configure el proyecto TodoListClient agregando el identificador de aplicación al archivo app.config .

1. En el portal Registros de aplicaciones, en la página Información general, copie el valor del identificador de aplicación (cliente).

2. En la carpeta raíz del proyecto TodoListClient, abra el archivo app.config y pegue el valor de Id. de aplicación en el ida:ClientId parámetro .

ASP.NET Core

1. En el IDE, abra la carpeta del proyecto, ms-identity-ciam-dotnet-tutorial/2-Authorization/3-call-own-api-dotnet-core-daemon/ToDoListAPI, que contiene el ejemplo.

2. Abra el archivo appsettings.json, que contiene el siguiente fragmento de código:

   {
     "AzureAd": {
       "Instance": "Enter_the_Authority_URL_Here", //For external tenants, use instance in the form of "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/"
       "TenantId": "Enter_the_Tenant_Id_Here",
       "ClientId": "Enter_the_Application_Id_Here",
       "Scopes": {
         "Read": ["ToDoList.Read", "ToDoList.ReadWrite"],
         "Write": ["ToDoList.ReadWrite"]
       },
       "AppPermissions": {
         "Read": ["ToDoList.Read.All", "ToDoList.ReadWrite.All"],
         "Write": ["ToDoList.ReadWrite.All"]
       }
     },
     "Logging": {...},
     "AllowedHosts": "*"
   }
   

   Busque los valores siguientes:

   • ClientId: el identificador de la aplicación, también conocido como el cliente. Reemplace el texto entre comillas por el valueidentificador de aplicación (cliente) que se registró anteriormente en la página Información general de la aplicación registrada.
   • TenantId: identificador del inquilino donde se registra la aplicación. Reemplace el texto value entre comillas por el valor de identificador de Directorio (inquilino) que se registró anteriormente en la página Descripción general de la aplicación registrada.
   • Instance : especifica el directorio desde el que la Biblioteca de autenticación de Microsoft (MSAL) puede solicitar tokens. Reemplace por Enter_the_Authority_URL_Here cualquiera de los siguientes valores en función de su escenario:
     • En el caso de los inquilinos de recursos, use https://login.microsoftonline.com/ como instancia.
     • En el caso de los inquilinos externos, agregue una dirección URL de autoridad en forma de https://<Enter_the_Tenant_Subdomain_Here>.ciamlogin.com/

Ejecutar la aplicación de ejemplo

ASP.NET

Inicie ambos proyectos. Para los usuarios de Visual Studio;

1. Haga clic con el botón derecho en la solución de Visual Studio y seleccione Propiedades.

2. En Propiedades comunes, seleccione Proyecto de inicio y, a continuación, Varios proyectos de inicio.

3. En ambos proyectos, elija Iniciar como acción.

4. Asegúrese de que el servicio TodoListService se inicia primero moviendolo a la primera posición de la lista, con la flecha arriba.

Inicie sesión para ejecutar el proyecto TodoListClient.

1. Presione F5 para iniciar los proyectos. Se abre la página de servicio, así como la aplicación de escritorio.

2. En TodoListClient, en la esquina superior derecha, seleccione Iniciar sesión y, a continuación, inicie sesión con las mismas credenciales que usó para registrar la aplicación o inicie sesión como un usuario en el mismo directorio.

   Si inicia sesión por primera vez, es posible que se le pida que dé su consentimiento a la API web TodoListService.

   Para ayudarle a acceder a la API web TodoListService y manipular la lista To-Do, el inicio de sesión también solicita un token de acceso para el ámbito access_as_user.

Autorización previa de la aplicación cliente

Puede permitir que los usuarios de otros directorios accedan a la API web mediante la autorización previa de la aplicación cliente para acceder a la API web. Para ello, agregue el identificador de aplicación de la aplicación cliente a la lista de aplicaciones autenticadas previamente para la API web. Al agregar un cliente autenticado previamente, permite a los usuarios acceder a la API web sin tener que proporcionar consentimiento.

1. En el portal Registros de aplicaciones, abra las propiedades de la aplicación TodoListService.
2. En la sección Exponer una API , en Aplicaciones cliente autorizadas, seleccione Agregar una aplicación cliente.
3. En el cuadro Id. de cliente , pegue el identificador de aplicación de la aplicación TodoListClient.
4. En la sección Ámbitos autorizados , seleccione el ámbito de la api://<Application ID>/access_as_user API web.
5. Seleccione Agregar aplicación.

Ejecución del proyecto

1. Presione F5 para ejecutar el proyecto. Se abre la aplicación TodoListClient.
2. En la esquina superior derecha, seleccione Iniciar sesión e inicie sesión con una cuenta microsoft personal, como una cuenta de live.com o hotmail.com , o una cuenta profesional o educativa.

Opcional: Limitar el acceso de inicio de sesión a determinados usuarios

De forma predeterminada, cualquier cuenta personal, como outlook.com o cuentas de live.com , o cuentas profesionales o educativas de organizaciones integradas con microsoft Entra ID pueden solicitar tokens y acceder a la API web.

Para especificar quién puede iniciar sesión en la aplicación, cambie la TenantId propiedad en el archivo appsettings.json .

ASP.NET Core

1. Ejecute el siguiente comando desde la raíz del directorio del proyecto de API web para iniciar la aplicación:

   dotnet run
   

2. Si todo funcionó correctamente, el terminal muestra una salida similar a la siguiente:

    Building...
        info: Microsoft.Hosting.Lifetime[14]
              Now listening on: https://localhost:{port}
        info: Microsoft.Hosting.Lifetime[0]
              Application started. Press Ctrl+C to shut down.
        info: Microsoft.Hosting.Lifetime[0]
              Hosting environment: Development
   ...
   

   Registre el número de puerto en la dirección URL https://localhost:{port}.

3. Para comprobar que el punto de conexión está protegido, actualice la dirección URL base en el siguiente comando cURL para que coincida con la que recibió en el paso anterior y, a continuación, ejecute el comando:

   curl -k -X GET https://localhost:<your-api-port>/api/todolist -w "%{http_code}\n"
   

   La respuesta esperada es 401 No autorizado.

Pasos siguientes

Aprenda a proteger una API web de ASP.NET Core con la plataforma de identidad de Microsoft.

Tutorial: Compilación y protección de una API web de ASP.NET Core con la plataforma de identidad de Microsoft