Configurare un'app per dispositivi mobili che chiama le API Web

Articolo
10/24/2023

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 framework di creazione.

Librerie Microsoft che supportano le app per dispositivi mobili

Le librerie Microsoft seguenti supportano le app per dispositivi mobili:

Piattaforma	Progetto in GitHub	Pacchetto	Ottenere avviata	Disponibile a livello generale (GA) o Anteprima^{pubblica 1}
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 PublicClientApplication classe . 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 MSALPublicClientApplication classe . 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.

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 With<Parameter> metodi impostano l'elemento padre dell'interfaccia utente, eseguono l'override dell'autorità predefinita, specificano un nome client e una versione per i dati di 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 dati di telemetria e registrazione.

Le sezioni seguenti forniscono altre 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. Nello stesso modo in UWP, potresti voler passare la finestra padre. Lo si passa quando si acquisisce il token. Tuttavia, quando si crea l'app, è anche possibile specificare un callback come delegato che restituisce 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 esposte in PublicClientApplicationOptions, vedere la documentazione di riferimento.

Attività per Xamarin iOS

Se si usa MSAL.NET in Xamarin iOS, eseguire le attività seguenti.

Per altre informazioni, vedere Considerazioni su Xamarin iOS.

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 di Xamarin.Android con MSAL.NET.

Attività per la piattaforma UWP

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

Per altre informazioni, vedi 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 i dispositivi registrati con Microsoft Entra ID. Quando si usa l'accesso SSO, gli utenti non devono accedere a ogni applicazione.
Identificazione del 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 WithBroker() parametro quando si chiama il PublicClientApplicationBuilder.CreateApplication metodo . Per impostazione predefinita, .WithBroker() è impostato su true.

Per abilitare l'autenticazione negoziata 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 negoziata in Android.

Abilitare il broker per MSAL per iOS e macOS

L'autenticazione negoziata è abilitata per impostazione predefinita per gli 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. Nei due set di istruzioni, alcuni dei passaggi differiscono.

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 PublicClientApplication classe. Usare il WithBroker() parametro quando si crea la PublicClientApplication classe tramite PublicClientApplicationBuilder. Il WithBroker() parametro è 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 all'applicazione. Viene chiamato di nuovo usando il AppDelegate.OpenUrl metodo . Poiché MSAL attende la risposta dal broker, l'applicazione deve cooperare per chiamare MSAL.NET indietro. Per configurare questo comportamento, aggiornare il AppDelegate.cs file 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 viene avviata l'applicazione. È un'opportunità per elaborare la risposta dal broker e completare il processo di autenticazione che MSAL.NET avviato.

Passaggio 3: Impostare un uiViewController()

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

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

In AppDelegate.csimpostare su App.RootViewController un nuovo UIViewController()oggetto . 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."

AcquireTokenInteractive Nella chiamata 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();

AcquireToken Nella chiamata:

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 round trip, registrare lo schema URL dell'app nel Info.plist file.

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

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

$"msauth.(BundleId)"

In questo caso, BundleId identifica in modo univoco il dispositivo. 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 è installato nel dispositivo. In iOS 9 Apple ha bloccato gli schemi per cui un'applicazione può eseguire query.

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

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

Autenticazione negoziata per MSAL per iOS e macOS

L'autenticazione negoziata è abilitata per impostazione predefinita per gli scenari di 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 openURL metodo . Poiché MSAL attende la risposta dal broker, l'applicazione deve cooperare per richiamare MSAL. Configurare questa funzionalità aggiornando il AppDelegate.m file 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 è stato adottato UISceneDelegate in iOS 13 o versione successiva, inserire invece il callback MSAL in scene:openURLContexts: .UISceneDelegate MSAL handleMSALResponse:sourceApplication: deve essere chiamato una sola volta per ogni URL.

Per altre informazioni, vedere la documentazione di Apple.

Passaggio 2: Registrare uno schema URL

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

Per registrare uno schema per l'app:

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

$"msauth.(BundleId)"

In questo caso, BundleId identifica in modo univoco il dispositivo. 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 le chiamate all'app Microsoft Authenticator, se installata.

Nota

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

Ecco un esempio di come aggiungere LSApplicationQueriesSchemes:

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

Autenticazione negoziata per Xamarin.Android

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

Passaggi successivi

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

Configurare un'app per dispositivi mobili che chiama le API Web

Librerie Microsoft che supportano le 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 Xamarin iOS

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 negoziata 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 negoziata per Xamarin.Android

Passaggi successivi

Risorse aggiuntive