Configuración de una aplicación móvil que llama a las API web

Artículo
10/25/2023

Una vez creada la aplicación, aprenderá a configurar el código con los parámetros de registro de la aplicación. Las aplicaciones móviles presentan algunas complejidades relacionadas con la adaptación a su marco de creación.

Bibliotecas de Microsoft que admiten aplicaciones móviles

Las siguientes bibliotecas de Microsoft admiten aplicaciones móviles:

Plataforma	Proyecto en GitHub	Paquete	Introducción iniciado	Disponible con carácter general (GA) o Versión preliminar pública¹
Android (Java)	MSAL de Android	MSAL	Guía de inicio rápido	GA
Android (Kotlin)	MSAL de Android	MSAL	—	GA
iOS (Swift/Obj-C)	MSAL para iOS y macOS	MSAL	Tutorial	GA
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	GA

¹ Términos de licencia universal de Online Services se aplican a las bibliotecas de Versión preliminar pública.

Creación de una instancia de la aplicación

Android

Las aplicaciones móviles usan la clase PublicClientApplication. Aquí se muestra cómo crear una instancia:

PublicClientApplication sampleApp = new PublicClientApplication(
                    this.getApplicationContext(),
                    R.raw.auth_config);

iOS

Las aplicaciones móviles de iOS necesitan crear una instancia de la clase MSALPublicClientApplication. Para crear una instancia de la clase, use el código siguiente.

NSError *msalError = nil;

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

Las propiedades MSALPublicClientApplicationConfig adicionales pueden invalidar la autoridad predeterminada, especificar un URI de redirección o cambiar el comportamiento del almacenamiento en caché del token de MSAL.

Xamarin o UWP

En la siguiente sección se explica cómo crear instancias de la aplicación para las aplicaciones de Xamarin.iOS, de Xamarin.Android y para UWP.

Nota:

Ni la versión 4.61.0 de MSAL.NET ni las posteriores proporcionan compatibilidad con la Plataforma universal de Windows (UWP), Xamarin Android y Xamarin iOS. Se recomienda migrar las aplicaciones de Xamarin a marcos modernos, como MAUI. Obtenga más información sobre el desuso en el Anuncio del próximo desuso de MSAL.NET para Xamarin y UWP.

Creación de una instancia de la aplicación

En Xamarin o UWP, la manera más sencilla de crear una instancia de la aplicación es mediante el código siguiente. En este código, ClientId es el GUID de la aplicación registrada.

var app = PublicClientApplicationBuilder.Create(clientId)
                                        .Build();

Otros métodos With<Parameter> establecen el elemento primario de la interfaz de usuario, invalidan la autoridad predeterminada, especifican un nombre de cliente y una versión para la telemetría, especifican un URI de redirección y especifican el generador HTTP que se va a usar. El generador HTTP podría usarse, por ejemplo, para controlar los servidores proxy y para especificar la telemetría y el registro.

En las secciones siguientes se proporciona más información sobre la creación de instancias de la aplicación.

Especificación de la ventana, la actividad o la interfaz de usuario primaria

En Android, pase la actividad principal antes de realizar la autenticación interactiva. En iOS, cuando se use un agente, pase ViewController. Del mismo modo en UWP, puede que quiera pasar la ventana primaria. Se pasa al adquirir el token. No obstante, al crear la aplicación, también puede especificar una devolución de llamada como un delegado que devuelve UIParent.

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .ParentActivityOrWindowFunc(() => parentUi)
  .Build();

En Android, se recomienda que use CurrentActivityPlugin. El código del generador PublicClientApplication resultante es similar al de este ejemplo:

// Requires MSAL.NET 4.2 or above
var pca = PublicClientApplicationBuilder
  .Create("<your-client-id-here>")
  .WithParentActivityOrWindow(() => CrossCurrentActivity.Current)
  .Build();

Búsqueda de más parámetros de compilación de aplicaciones

Para obtener una lista de todos los métodos que están disponibles en PublicClientApplicationBuilder, consulte la lista de métodos.

Para obtener una descripción de todas las opciones que se exponen en PublicClientApplicationOptions, consulte la documentación de referencia.

Tareas de MSAL para iOS y macOS

Estas tareas son necesarias cuando se usa MSAL para iOS y macOS:

Tareas para Xamarin.Android

Si usa Xamarin.Android, realice las tareas siguientes:

Para obtener más información, consulte Consideraciones sobre Xamarin.Android.

Para conocer las consideraciones sobre los exploradores en Android, consulte Consideraciones específicas de Xamarin.Android con MSAL.NET.

Tareas para UWP

En UWP, puede usar redes corporativas. En las siguientes secciones se explican las tareas que debe completar en el escenario corporativo.

Para obtener más información, consulte Consideraciones específicas de UWP con MSAL.NET.

Configuración de la aplicación para usar el agente

En Android e iOS, los agentes permiten:

Inicio de sesión único (SSO): Puede usar el SSO para los dispositivos registrados con Microsoft Entra ID. Al usar SSO, los usuarios no tienen que iniciar sesión en cada aplicación.
Identificación de dispositivos: Esta opción habilita las directivas de acceso condicional relacionadas con los dispositivos de Microsoft Entra. El proceso de autenticación usa el certificado de dispositivo que se creó al unir el dispositivo al área de trabajo.
Comprobación de identificación de la aplicación: cuando una aplicación llama al agente, pasa su URL de redireccionamiento. A continuación, el agente lo comprueba.

Habilitación del agente en Xamarin

Para habilitar el agente en Xamarin, use el parámetro WithBroker() al llamar al método PublicClientApplicationBuilder.CreateApplication. De manera predeterminada, .WithBroker() se establece en true.

Para habilitar la autenticación asincrónica para Xamarin.iOS, siga los pasos de la sección Xamarin.iOS de este artículo.

Habilitación del agente para MSAL para Android

Consulte Autenticación asincrónica en Android para obtener información sobre cómo habilitar un agente en Android.

Habilitación del agente para MSAL para iOS y macOS

La autenticación con agente está habilitada de forma predeterminada para los escenarios de Microsoft Entra en MSAL para iOS y macOS.

En las secciones siguientes se proporcionan instrucciones para configurar la aplicación para la compatibilidad con la autenticación asincrónica para MSAL para Xamarin.iOS o MSAL para iOS y macOS. En los dos conjuntos de instrucciones, algunos de los pasos difieren.

Habilitación de la autenticación asincrónica para Xamarin iOS

Siga los pasos de esta sección para permitir que la aplicación de Xamarin.iOS pueda hablar con la aplicación Microsoft Authenticator.

Paso 1: Habilitar la compatibilidad con el agente

La compatibilidad con el agente está deshabilitada de manera predeterminada. Se habilita para una clase PublicClientApplication individual. Use el parámetro WithBroker() cuando cree la clase PublicClientApplication a través de PublicClientApplicationBuilder. El parámetro WithBroker() se establece en true de forma predeterminada.

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos) // $"msauth.{Bundle.Id}://auth" (see step 6 below)
                .Build();

Paso 2: Actualizar AppDelegate para controlar la devolución de llamada

Cuando MSAL.NET llama al agente, el agente vuelve a llamar a la aplicación. Vuelve a llamar mediante el método AppDelegate.OpenUrl. Como MSAL espera la respuesta del agente, la aplicación debe cooperar para volver a llamar a MSAL.NET. Para configurar este comportamiento, actualice el archivo AppDelegate.cs para invalidar el método, como se muestra en el código siguiente.

public override bool OpenUrl(UIApplication app, NSUrl url,
                             string sourceApplication,
                             NSObject annotation)
{
 if (AuthenticationContinuationHelper.IsBrokerResponse(sourceApplication))
 {
  AuthenticationContinuationHelper.SetBrokerContinuationEventArgs(url);
  return true;
 }
 else if (!AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(url))
 {
  return false;
 }
 return true;
}

Este método se invoca cada vez que se inicia la aplicación. Es una oportunidad para procesar la respuesta del agente y finalizar el proceso de autenticación iniciado por MSAL.NET.

Paso 3: Establecer un UIViewController()

Normalmente, para Xamarin iOS, no es necesario establecer una ventana de objeto. Pero en este caso se debe establecer para poder enviar y recibir respuestas de un agente. Para establecer una ventana de objeto, en AppDelegate.cs, deberá establecer un elemento ViewController.

Para establecer la ventana de objeto, siga estos pasos:

En AppDelegate.cs, establezca App.RootViewController en un nuevo UIViewController(). Esta configuración garantiza que la llamada al agente incluye UIViewController. Si no se establece correctamente, puede obtener este error:

"uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker."

En la llamada AcquireTokenInteractive, use .WithParentActivityOrWindow(App.RootViewController). Pase la referencia a la ventana de objeto que va a usar. Este es un ejemplo:

En App.cs:

   public static object RootViewController { get; set; }

En AppDelegate.cs:

   LoadApplication(new App());
   App.RootViewController = new UIViewController();

En la llamada AcquireToken:

result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow(App.RootViewController)
             .ExecuteAsync();

Paso 4: Registrar un esquema de dirección URL

MSAL.NET usa direcciones URL para invocar al agente y devolver la respuesta del agente a la aplicación. Para finalizar el recorrido de ida y vuelta, registre el esquema de dirección URL de la aplicación en el archivo Info.plist.

Para registrar el esquema de dirección URL de la aplicación, siga estos pasos:

Agregue a CFBundleURLSchemes el prefijo msauth.
Agregue CFBundleURLName al final. Siga este patrón:

$"msauth.(BundleId)"

Aquí, BundleId identifica su dispositivo de manera exclusiva. Por ejemplo, si BundleId es yourcompany.xforms, el esquema de dirección URL es msauth.com.yourcompany.xforms.

Este esquema de dirección URL se convertirá en parte del URI de redirección que se usa para identificar de forma única la aplicación cuando recibe la respuesta del agente.
```
 <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.xforms</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>msauth.com.yourcompany.xforms</string>
        </array>
      </dict>
    </array>
```

Paso 5: Agregarlo a la sección LSApplicationQueriesSchemes

MSAL usa –canOpenURL: para comprobar si el agente está instalado en el dispositivo. En iOS 9, Apple ha bloqueado los esquemas que puede consultar una aplicación.

Agregue msauthv2 a la sección LSApplicationQueriesSchemes del archivo Info.plist, como en el ejemplo de código siguiente:

<key>LSApplicationQueriesSchemes</key>
    <array>
      <string>msauthv2</string>
    </array>

Autenticación asincrónica de MSAL para iOS y macOS

La autenticación con agente está habilitada de forma predeterminada para los escenarios de Microsoft Entra.

Paso 1: Actualizar AppDelegate para controlar la devolución de llamada

Cuando MSAL para iOS y macOS llama al agente, este a su vez vuelve a llamar a la aplicación con el método openURL. Dado que MSAL espera la respuesta del agente, la aplicación debe cooperar para volver a llamar a MSAL. Para configurar este comportamiento, actualice el archivo AppDelegate.m para invalidar el método, como se muestra en los ejemplos de código siguientes.

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [MSALPublicClientApplication handleMSALResponse:url
                                         sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

        guard let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String else {
            return false
        }

        return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApplication)
    }

Si adoptó UISceneDelegate en iOS 13 o posterior, coloque la devolución de llamada de MSAL en scene:openURLContexts: de UISceneDelegate en su lugar. MSAL handleMSALResponse:sourceApplication: solo debe llamarse una vez para cada dirección URL.

Para más información, consulte la documentación de Apple.

Paso 2: Registrar un esquema de dirección URL

MSAL para iOS y macOS usa direcciones URL para invocar al agente y devolver su respuesta a la aplicación. Para finalizar el recorrido de ida y vuelta, registre un esquema de dirección URL para la aplicación en el archivo Info.plist.

Para registrar un esquema para la aplicación:

Prefije el esquema de la dirección URL personalizada con msauth.
Agregue el identificador del paquete al final del esquema. Siga este patrón:

$"msauth.(BundleId)"

Aquí, BundleId identifica su dispositivo de manera exclusiva. Por ejemplo, si BundleId es yourcompany.xforms, el esquema de dirección URL es msauth.com.yourcompany.xforms.

Este esquema de dirección URL se convertirá en parte del URI de redirección que se usa para identificar de forma única la aplicación cuando recibe la respuesta del agente. Asegúrese de que el URI de redirección en el formato msauth.(BundleId)://auth esté registrado para su aplicación.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Paso 3: Agregar LSApplicationQueriesSchemes

Agregue LSApplicationQueriesSchemes para permitir llamadas a la aplicación Microsoft Authenticator, si está instalada.

Nota:

El esquema msauthv3 es necesario si la aplicación se ha compilado con Xcode 11 y versiones posteriores.

Este es un ejemplo sobre cómo agregar LSApplicationQueriesSchemes:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>msauthv2</string>
  <string>msauthv3</string>
</array>

Autenticación asincrónica para Xamarin.Android

Vea Autenticación con agente en Xamarin.Android para más información sobre cómo habilitar un agente en Android.

Pasos siguientes

Avance al siguiente artículo de este escenario, Obtención de un token.

Compartir a través de

Configuración de una aplicación móvil que llama a las API web

Bibliotecas de Microsoft que admiten aplicaciones móviles

Creación de una instancia de la aplicación

Android

iOS

Xamarin o UWP

Creación de una instancia de la aplicación

Especificación de la ventana, la actividad o la interfaz de usuario primaria

Búsqueda de más parámetros de compilación de aplicaciones

Tareas de MSAL para iOS y macOS

Tareas para Xamarin.Android

Tareas para UWP

Configuración de la aplicación para usar el agente

Habilitación del agente en Xamarin

Habilitación del agente para MSAL para Android

Habilitación del agente para MSAL para iOS y macOS

Habilitación de la autenticación asincrónica para Xamarin iOS

Paso 1: Habilitar la compatibilidad con el agente

Paso 2: Actualizar AppDelegate para controlar la devolución de llamada

Paso 3: Establecer un UIViewController()

Paso 4: Registrar un esquema de dirección URL

Paso 5: Agregarlo a la sección LSApplicationQueriesSchemes

Autenticación asincrónica de MSAL para iOS y macOS

Paso 1: Actualizar AppDelegate para controlar la devolución de llamada

Paso 2: Registrar un esquema de dirección URL

Paso 3: Agregar LSApplicationQueriesSchemes

Autenticación asincrónica para Xamarin.Android

Pasos siguientes

Comentarios

Recursos adicionales