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

  • Artículo

La siguiente guía rápida usa un ejemplo de código que demuestra cómo proteger una API web ASP.NET al restringir el acceso a sus recursos solo a cuentas autorizadas. El ejemplo admite la autorización de cuentas personales de Microsoft y cuentas de cualquier organización de Microsoft Entra.

El artículo también usa una aplicación Windows Presentation Foundation (WPF) como ejemplo de cómo solicitar un token de acceso para acceder a una API web.

Requisitos previos

Clonación o descarga del ejemplo

El ejemplo de código se puede obtener de dos maneras:

  • Clonación desde el shell o la línea de comandos:

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

  • Descarga en un archivo .zip.

Sugerencia

Se recomienda extraer el archivo o clonar el repositorio en un directorio próximo a la raíz de la unidad para evitar los errores provocados por las limitaciones de longitud de la ruta de acceso en Windows.

Registro de la API web (TodoListService)

Sugerencia

Los pasos de este artículo pueden variar ligeramente en función del portal desde donde comienza.

Registre la API web en Registros de aplicaciones, en Azure Portal.

  1. Inicie sesión en el Centro de administración de Microsoft Entra como Administrador de aplicaciones en la nube.

  2. Si tiene acceso a varios inquilinos, use el icono Configuración del menú superior para cambiar al inquilino en el que desea registrar la aplicación desde el menú Directorios y suscripciones.

  3. Vaya a Identidad>Aplicaciones>Registros de aplicaciones y seleccione Nuevo registro.

  4. Escriba el Nombre de la aplicación, por ejemplo AppModelv2-NativeClient-DotNet-TodoListService. Los usuarios de la aplicación pueden ver este nombre, el cual se puede cambiar más tarde.

  5. En Supported account types (Tipos de cuenta admitidos), seleccione Account in any organizational directory (Cuentas en cualquier directorio organizativo).

  6. Seleccione Registrar para crear la aplicación.

  7. En la página Overview (Información general) de la aplicación, busque el valor de Application (client) ID (Id. de cliente de la aplicación) y regístrelo para usarlo más tarde. Lo necesitará para ajustar el archivo de configuración de Visual Studio para este proyecto (es decir, ClientId en el archivo TodoListService\appsettings.json).

  8. En Administrar, seleccione Exponer una API>Agregar un ámbito. Acepte el URI de identificador de aplicación propuesto (api://{clientId}), seleccione Save and Continue (Guardar y continuar) y escriba la información siguiente:

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

  9. Seleccione la opción Agregar un ámbito.

Configuración del proyecto del servicio

Configure el proyecto de servicio para que coincida con la API web registrada.

  1. Abra la solución en Visual Studio y, después, el archivo appsettings.json en la raíz de proyecto de TodoListService.

  2. Reemplace el valor de Enter_the_Application_Id_here por el valor del identificador de cliente (identificador de la aplicación) de la aplicación que registró en el portal Registros de aplicaciones en las propiedades ClientID y Audience.

Incorporación del nuevo ámbito al archivo app.config

Para agregar el nuevo ámbito al archivo app.config de TodoListClient, haga lo siguiente:

  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 la aplicación tiene el formato siguiente: api://{TodoListService-Application-ID}/access_as_user (donde {TodoListService-Application-ID} es el GUID que representa el identificador de la aplicación TodoListService).

Registro de la aplicación web (TodoListClient)

Registre la aplicación TodoListClient en Registros de aplicaciones, en Azure Portal, y, luego, configure el código en el proyecto TodoListClient. Si el cliente y el servidor se consideran la misma aplicación también puede volver a usar la aplicación que se registró en el paso 2. Use la misma aplicación si quiere que los usuarios inicien sesión con su cuenta personal de Microsoft.

Registre la aplicación

Para registrar la aplicación TodoListClient, haga lo siguiente:

  1. Inicie sesión en el Centro de administración de Microsoft Entra como Administrador de aplicaciones en la nube.

  2. Vaya a Identidad>Aplicaciones>Registros de aplicaciones y seleccione Nuevo registro.

  3. Seleccione Nuevo registro.

  4. Cuando aparezca la página de registro de aplicaciones, escriba la información de registro de la aplicación:

    1. En la sección Name (Nombre), escriba un nombre con sentido para la aplicación que se mostrará a los usuarios (por ejemplo, NativeClient-DotNet-TodoListClient).
    2. En Supported account types (Tipos de cuenta admitidos), seleccione Account in any organizational directory (Cuentas en cualquier directorio organizativo).
    3. Seleccione Registrar para crear la aplicación.

    Nota:

    En el archivo app.config del 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 con una cuenta personal de Microsoft (porque seleccionó Cuentas en cualquier directorio organizativo en el 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, luego, haga lo siguiente para agregar una plataforma:

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

  6. Seleccione Permisos de API y, luego, haga lo siguiente 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 o el nombre que especificara para la API web.
    4. Seleccione la casilla del permiso access_as_user si aún no lo está. Si es necesario, utilice el cuadro de búsqueda.
    5. Seleccione el botón Agregar permisos.

Configurar el 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 Overview (Información general), copie el valor de Application (client) ID (Id. de cliente de la aplicación).

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

Ejecución de los proyectos

Inicie ambos proyectos. Para 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, haga clic en Proyectos de inicio múltiples.

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

  4. Para asegurarse de que el servicio TodoListService se inicie primero, muévalo 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 del servicio, así como la aplicación de escritorio.

  2. En la parte superior derecha de TodoListClient, seleccione Iniciar sesión e inicie sesión con las mismas credenciales del registro de la aplicación o con un usuario del mismo directorio.

    Si es la primera vez que inicia sesión, 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 a manipular la lista To-Do, en el inicio de sesión también se solicita un token de acceso al ámbito access_as_user.

Preautorización 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 la aplicación cliente a la lista de aplicaciones previamente autorizadas de la API web. Al agregar un cliente previamente autorizado, permite a los usuarios acceder a la API web sin tener que dar su consentimiento.

  1. En el portal Registros de aplicaciones, abra las propiedades de la aplicación TodoListService.
  2. En la sección Expose an API (Exponer una API), en Authorized client applications (Aplicaciones cliente autorizadas), seleccione Add a client application (Agregar una aplicación cliente).
  3. En el cuadro Client ID (Id. de cliente), pegue el identificador de la aplicación TodoListClient.
  4. En la sección Authorized scopes (Ámbitos autorizados), seleccione el ámbito de esta API web: api://<Application ID>/access_as_user.
  5. Seleccione Agregar una aplicación.

Ejecución del proyecto

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

Opcional: limitación del acceso de inicio de sesión a determinados usuarios

De forma predeterminada, cualquier cuenta personal, como outlook.com o live.com, o profesional o educativa de las organizaciones integradas con Microsoft Entra ID puede solicitar tokens y acceder a la API web.

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

Ayuda y soporte técnico

Si necesita ayuda, desea informar de un problema o desea obtener información sobre las opciones de soporte técnico, consulte Opciones de ayuda y soporte técnico para desarrolladores.

Pasos siguientes

Para más información, compile una API web de ASP.NET Core protegida en la siguiente serie de tutoriales:

Tutorial de API web protegida