Configurare un'app per dispositivi mobili che chiama API Web

Articolo
06/21/2024

Dopo aver creato l'applicazione, si apprenderà come configurare il codice usando i parametri di registrazione dell'app. Le applicazioni per dispositivi mobili presentano alcune complessità correlate all'adattamento al loro framework di creazione.

Librerie Microsoft che supportano app per dispositivi mobili

Le librerie Microsoft seguenti supportano app per dispositivi mobili:

Piattaforma	Progetto in GitHub	Pacchetto	Recupero avviata	Disponibile a livello generale (GA) o Anteprima pubblica¹
Android (Java)	MSAL Android	MSAL	Guida introduttiva	Disponibilità generale
Android (Kotlin)	MSAL Android	MSAL	—	Disponibilità generale
iOS (Swift/Obj-C)	MSAL per iOS e macOS	MSAL	Esercitazione	Disponibilità generale
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	Disponibilità generale

^{1 Le} condizioni di licenza universali per i servizi online si applicano alle librerie in anteprima pubblica.

Creare un'istanza dell'applicazione

Android

Le applicazioni per dispositivi mobili usano la classe PublicClientApplication. Ecco come crearne un'istanza:

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

iOS

Le applicazioni per dispositivi mobili in iOS devono creare un'istanza della classe MSALPublicClientApplication. Per creare un'istanza della classe, usare il codice seguente.

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 */}

Altre proprietà MSALPublicClientApplicationConfig possono eseguire l'override dell'autorità predefinita, specificare un URI di reindirizzamento o modificare il comportamento della memorizzazione nella cache dei token MSAL.

Xamarin o UWP

Questa sezione illustra come creare un'istanza dell'applicazione per le app Xamarin.iOS, Xamarin.Android e UWP.

Nota

MSAL.NET versioni 4.61.0 e successive non forniscono supporto per la piattaforma UWP (Universal Windows Platform), Xamarin Android e Xamarin iOS. È consigliabile eseguire la migrazione delle applicazioni Xamarin a framework moderni come MAUI. Altre informazioni sulla deprecazione in Annuncio della prossima deprecazione di MSAL.NET per Xamarin e UWP.

Creare un'istanza dell'applicazione

In Xamarin o UWP, il modo più semplice per creare un'istanza dell'applicazione consiste nell'usare il codice seguente. In questo codice, ClientId è il GUID dell'app registrata.

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

Altri metodi With<Parameter> impostano l'elemento padre dell'interfaccia utente, eseguono l'override dell'autorità predefinita, specificano un nome client e una versione per la telemetria, specificano un URI di reindirizzamento e specificano la factory HTTP da usare. La factory HTTP può essere usata, ad esempio, per gestire proxy e per specificare telemetria e registrazione.

Le sezioni seguenti forniscono ulteriori informazioni sulla creazione di istanze dell'applicazione.

Specificare l'interfaccia utente padre, la finestra o l'attività

In Android, passare l'attività padre prima di eseguire l'autenticazione interattiva. In iOS, quando si usa un broker, passare ViewController. Analogamente, nella piattaforma UWP si potrebbe voler passare la finestra padre. Questa si passa quando si acquisisce il token. Tuttavia, quando si crea l'app è anche possibile specificare un callback come delegato che restituisca UIParent.

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

In Android, è consigliabile usare CurrentActivityPlugin. Il codice del generatore risultante PublicClientApplication è simile all'esempio seguente:

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

Altri parametri di compilazione delle app

Per un elenco di tutti i metodi disponibili in PublicClientApplicationBuilder, vedere l'elenco Metodi.

Per una descrizione di tutte le opzioni elencate in PublicClientApplicationOptions, vedere la documentazione di riferimento.

Attività per MSAL per iOS e macOS

Queste attività sono necessarie quando si usa MSAL per iOS e macOS:

Attività per Xamarin.Android

Se si usa Xamarin.Android, eseguire le attività seguenti:

Per altre informazioni, vedere Considerazioni su Xamarin.Android.

Per considerazioni sui browser in Android, vedere Considerazioni specifiche su Xamarin.Android con MSAL.NET.

Attività per la piattaforma UWP

Nella piattaforma UWP, è possibile usare reti aziendali. Le sezioni seguenti illustrano le attività da completare nello scenario aziendale.

Per altre informazioni, vedere Considerazioni specifiche della piattaforma UWP con MSAL.NET.

Configurare l'applicazione per l'uso del broker

In Android e iOS, i broker abilitano:

Single Sign-On (SSO):è possibile usare SSO per dispositivi registrati con Microsoft Entra ID. Quando si usa l'accesso SSO, gli utenti non hanno bisogno di accedere a ogni applicazione.
Identificazione dispositivo: questa impostazione abilita i criteri di accesso condizionale correlati ai dispositivi Microsoft Entra. Il processo di autenticazione usa il certificato del dispositivo creato quando il dispositivo è stato aggiunto all'area di lavoro.
Verifica dell'identificazione dell'applicazione: quando un'applicazione chiama il broker, passa l'URL di reindirizzamento. Quindi, il broker lo verifica.

Abilitare il broker in Xamarin

Per abilitare il broker in Xamarin, usare il parametro WithBroker() quando si chiama il metodo PublicClientApplicationBuilder.CreateApplication. Per impostazione predefinita, .WithBroker() è impostato su true.

Per abilitare l'autenticazione con broker per Xamarin.iOS, seguire la procedura descritta nella sezione Xamarin.iOS di questo articolo.

Abilitare il broker per MSAL per Android

Per informazioni sull'abilitazione di un broker in Android, vedere Autenticazione con broker in Android.

Abilitare il broker per MSAL per iOS e macOS

L'autenticazione con broker è abilitata per impostazione predefinita per scenari Microsoft Entra in MSAL per iOS e macOS.

Le sezioni seguenti forniscono istruzioni per configurare l'applicazione per il supporto dell'autenticazione negoziata per MSAL per Xamarin.iOS o MSAL per iOS e macOS. Alcuni passaggi differiscono tra i due set di istruzioni.

Abilitare l'autenticazione negoziata per Xamarin iOS

Seguire la procedura descritta in questa sezione per abilitare l'app Xamarin.iOS per comunicare con l'app Microsoft Authenticator.

Passaggio 1: Abilitare il supporto broker

Il supporto broker è disabilitato per impostazione predefinita. È possibile abilitarlo per una singola classe PublicClientApplication. Usare il parametro WithBroker() quando si crea la classe PublicClientApplication tramite PublicClientApplicationBuilder. Il parametro WithBroker() è impostato su true per impostazione predefinita.

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

Passaggio 2: Aggiornare AppDelegate per gestire il callback

Quando MSAL.NET chiama il broker, il broker richiama quindi l'applicazione. Richiama usando il metodo AppDelegate.OpenUrl. Poiché MSAL attende la risposta dal broker, l'applicazione deve cooperare per richiamare MSAL.NET. Per configurare questo comportamento, aggiornare il file AppDelegate.cs per eseguire l'override del metodo, come illustrato nel codice seguente.

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

Questo metodo viene richiamato ogni volta che l'applicazione viene avviata. Questa è un'opportunità per elaborare la risposta dal broker e completare il processo di autenticazione avviato da MSAL.NET.

Passaggio 3: Impostare un uiViewController()

Per Xamarin iOS, non è generalmente necessario impostare una finestra dell'oggetto. Ma, in questo caso, è necessario impostarne una in modo che sia possibile inviare e ricevere risposte da un broker. Per impostare una finestra dell'oggetto, impostare un oggetto AppDelegate.cs in ViewController.

Per impostare la finestra dell'oggetto, seguire questa procedura:

In AppDelegate.cs, impostare il App.RootViewController su un nuovo UIViewController(). Questa impostazione garantisce che la chiamata al broker includa UIViewController. Se non è impostata correttamente, è possibile che venga visualizzato questo errore:

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

Nella chiamata AcquireTokenInteractive, usare .WithParentActivityOrWindow(App.RootViewController). Passare il riferimento alla finestra dell'oggetto che verrà usata. Ecco un esempio:

In App.cs:

   public static object RootViewController { get; set; }

In AppDelegate.cs:

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

Nella chiamata AcquireToken:

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

Passaggio 4: Registrare uno schema URL

MSAL.NET usa gli URL per richiamare il broker e quindi restituire la risposta del broker all'app. Per completare il giro, registrare lo schema URL dell'app nel file Info.plist.

Per registrare lo schema URL dell'app, seguire questa procedura:

Prefisso CFBundleURLSchemes con msauth.
Aggiungere CFBundleURLName alla fine. Seguire questo modello:

$"msauth.(BundleId)"

In questo caso, BundleId identifica il dispositivo in modo univoco. Ad esempio, se BundleId è yourcompany.xforms, lo schema URL è msauth.com.yourcompany.xforms.

Questo schema URL diventerà parte dell'URI di reindirizzamento che identifica in modo univoco l'app quando riceve la risposta del broker.
```
 <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>
```

Passaggio 5: Aggiungere alla sezione LSApplicationQueriesSchemes

MSAL usa –canOpenURL: per verificare se il broker sia installato nel dispositivo. In iOS 9, Apple ha bloccato gli schemi di cui un'applicazione può eseguire query.

Aggiungere msauthv2 alla sezione LSApplicationQueriesSchemes del file Info.plist, come nell'esempio di codice seguente:

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

Autenticazione con broker per MSAL per iOS e macOS

L'autenticazione con broker è abilitata per impostazione predefinita per scenari Microsoft Entra.

Passaggio 1: Aggiornare AppDelegate per gestire il callback

Quando MSAL per iOS e macOS chiama il broker, il broker richiama l'applicazione usando il metodo openURL. Poiché MSAL attende la risposta dal broker, l'applicazione deve cooperare per richiamare MSAL. Configurare questa funzionalità aggiornando il file AppDelegate.m per eseguire l'override del metodo, come illustrato negli esempi di codice seguenti.

- (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)
    }

Se si è adottato UISceneDelegate in iOS 13 o versioni successive, inserire invece il callback MSAL nel scene:openURLContexts: di UISceneDelegate. MSAL handleMSALResponse:sourceApplication: deve essere chiamato una sola volta per ogni URL.

Per altre informazioni, vedere la documentazione Apple.

Passaggio 2: Registrare uno schema URL

MSAL per iOS e macOS usa URL per richiamare il broker e quindi restituire la risposta del broker all'app. Per completare il giro, registrare uno schema URL per l'app nel file Info.plist.

Per registrare uno schema per la propria app:

Anteporre il proprio schema URL personalizzato con msauth.
Aggiungere l'identificatore del bundle alla fine dello schema. Seguire questo modello:

$"msauth.(BundleId)"

In questo caso, BundleId identifica il dispositivo in modo univoco. Ad esempio, se BundleId è yourcompany.xforms, lo schema URL è msauth.com.yourcompany.xforms.

Questo schema URL diventerà parte dell'URI di reindirizzamento che identifica in modo univoco l'app quando riceve la risposta del broker. Assicurarsi che l'URI di reindirizzamento nel formato msauth.(BundleId)://auth sia registrato per l'applicazione.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Passaggio 3: Aggiungere LSApplicationQueriesSchemes

Aggiungere LSApplicationQueriesSchemes per consentire chiamate all'app Microsoft Authenticator, se installata.

Nota

Lo schema msauthv3 è necessario quando l'app viene compilata usando Xcode 11 e versioni successive.

Ecco un esempio che illustra come aggiungere LSApplicationQueriesSchemes:

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

Autenticazione con broker per Xamarin.Android

Per informazioni sull'abilitazione di un broker in Android, vedere Autenticazione con broker in Xamarin.Android.

Passaggi successivi

Passare all'articolo successivo in questo scenario, Acquisizione di un token.

Condividi tramite

Configurare un'app per dispositivi mobili che chiama API Web

Librerie Microsoft che supportano app per dispositivi mobili

Creare un'istanza dell'applicazione

Android

iOS

Xamarin o UWP

Creare un'istanza dell'applicazione

Specificare l'interfaccia utente padre, la finestra o l'attività

Altri parametri di compilazione delle app

Attività per MSAL per iOS e macOS

Attività per Xamarin.Android

Attività per la piattaforma UWP

Configurare l'applicazione per l'uso del broker

Abilitare il broker in Xamarin

Abilitare il broker per MSAL per Android

Abilitare il broker per MSAL per iOS e macOS

Abilitare l'autenticazione negoziata per Xamarin iOS

Passaggio 1: Abilitare il supporto broker

Passaggio 2: Aggiornare AppDelegate per gestire il callback

Passaggio 3: Impostare un uiViewController()

Passaggio 4: Registrare uno schema URL

Passaggio 5: Aggiungere alla sezione LSApplicationQueriesSchemes

Autenticazione con broker per MSAL per iOS e macOS

Passaggio 1: Aggiornare AppDelegate per gestire il callback

Passaggio 2: Registrare uno schema URL

Passaggio 3: Aggiungere LSApplicationQueriesSchemes

Autenticazione con broker per Xamarin.Android

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive