Konfigurera en mobilapp som anropar webb-API:er

Artikel
10/24/2023

När du har skapat ditt program får du lära dig hur du konfigurerar koden med hjälp av appregistreringsparametrarna. Mobila program har vissa komplexiteter som rör anpassning till deras ramverk för skapande.

Microsoft-bibliotek som stöder mobilappar

Följande Microsoft-bibliotek stöder mobilappar:

Plattform	Projekt på GitHub	Paket	Få komma igång	Allmänt tillgänglig (GA) eller Offentlig förhandsversion¹
Android (Java)	MSAL Android	MSAL	Snabbstart	Allmän tillgänglighet
Android (Kotlin)	MSAL Android	MSAL	—	Allmän tillgänglighet
iOS (Swift/Obj-C)	MSAL för iOS och macOS	MSAL	Självstudie	Allmän tillgänglighet
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—	Allmän tillgänglighet

¹ Universella licensvillkor för onlinetjänster gäller för bibliotek i offentlig förhandsversion.

Instansiera programmet

Android

Mobila program använder PublicClientApplication klassen . Så här instansierar du det:

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

iOS

Mobilprogram i iOS måste instansiera MSALPublicClientApplication klassen. Om du vill instansiera klassen använder du följande kod.

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

Ytterligare MSALPublicClientApplicationConfig-egenskaper kan åsidosätta standardutfärdare, ange en omdirigerings-URI eller ändra beteendet för CACHElagring av MSAL-token.

Xamarin eller UWP

I det här avsnittet beskrivs hur du instansierar programmet för Xamarin.iOS-, Xamarin.Android- och UWP-appar.

Kommentar

MSAL.NET version 4.61.0 och senare ger inte stöd för Universell Windows-plattform (UWP), Xamarin Android och Xamarin iOS. Vi rekommenderar att du migrerar dina Xamarin-program till moderna ramverk som MAUI. Läs mer om utfasningen i Meddelande om kommande utfasning av MSAL.NET för Xamarin och UWP.

Instansiera programmet

I Xamarin eller UWP är det enklaste sättet att instansiera programmet med hjälp av följande kod. I den här koden ClientId är GUID för din registrerade app.

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

Ytterligare With<Parameter> metoder anger det överordnade användargränssnittet, åsidosätter standardutfärdare, anger ett klientnamn och en version för telemetri, anger en omdirigerings-URI och anger den HTTP-fabrik som ska användas. HTTP-fabriken kan till exempel användas för att hantera proxyservrar och för att ange telemetri och loggning.

Följande avsnitt innehåller mer information om instansiering av programmet.

Ange det överordnade användargränssnittet, fönstret eller aktiviteten

På Android skickar du den överordnade aktiviteten innan du utför den interaktiva autentiseringen. I iOS, när du använder en asynkron meddelandekö, skickar du in ViewController. På samma sätt i UWP kanske du vill skicka in det överordnade fönstret. Du skickar in den när du hämtar token. Men när du skapar appen kan du också ange ett återanrop som ett ombud som returnerar UIParent.

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

På Android rekommenderar vi att du använder CurrentActivityPlugin. Den resulterande PublicClientApplication builder-koden ser ut som i det här exemplet:

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

Hitta fler appbyggparametrar

En lista över alla metoder som är tillgängliga på PublicClientApplicationBuilderfinns i listan Metoder.

En beskrivning av alla alternativ som visas i finns i PublicClientApplicationOptionsreferensdokumentationen.

Uppgifter för MSAL för iOS och macOS

Dessa uppgifter är nödvändiga när du använder MSAL för iOS och macOS:

Uppgifter för Xamarin.Android

Om du använder Xamarin.Android utför du följande uppgifter:

Mer information finns i Xamarin.Android-överväganden.

Överväganden om webbläsare på Android finns i Xamarin.Android-specifika överväganden med MSAL.NET.

Uppgifter för UWP

På UWP kan du använda företagsnätverk. I följande avsnitt beskrivs de uppgifter som du bör utföra i företagsscenariot.

Mer information finns i UWP-specifika överväganden med MSAL.NET.

Konfigurera programmet så att det använder asynkron meddelandekö

I Android och iOS aktiverar koordinatorer:

Enkel inloggning (SSO): Du kan använda enkel inloggning för enheter som är registrerade med Microsoft Entra-ID. När du använder enkel inloggning behöver användarna inte logga in på varje program.
Enhetsidentifiering: Den här inställningen aktiverar principer för villkorlig åtkomst som är relaterade till Microsoft Entra-enheter. Autentiseringsprocessen använder enhetscertifikatet som skapades när enheten anslöts till arbetsplatsen.
Verifiering av programidentifiering: När ett program anropar asynkron meddelandekö skickas dess omdirigerings-URL. Sedan verifierar mäklaren det.

Aktivera asynkron meddelandekö på Xamarin

Om du vill aktivera asynkron meddelandekö på Xamarin använder du parametern WithBroker() när du anropar PublicClientApplicationBuilder.CreateApplication metoden. Som standard .WithBroker() är värdet true.

Om du vill aktivera asynkron autentisering för Xamarin.iOS följer du stegen i avsnittet Xamarin.iOS i den här artikeln.

Aktivera asynkron meddelandekö för MSAL för Android

Information om hur du aktiverar en broker på Android finns i Asynkron autentisering på Android.

Aktivera asynkron meddelandekö för MSAL för iOS och macOS

Asynkron autentisering är aktiverat som standard för Microsoft Entra-scenarier i MSAL för iOS och macOS.

Följande avsnitt innehåller instruktioner för att konfigurera programmet för stöd för asynkron autentisering för msal för Xamarin.iOS eller MSAL för iOS och macOS. I de två uppsättningarna med instruktioner skiljer sig vissa steg åt.

Aktivera asynkron autentisering för Xamarin iOS

Följ stegen i det här avsnittet om du vill att Xamarin.iOS-appen ska kunna kommunicera med Microsoft Authenticator-appen .

Steg 1: Aktivera stöd för asynkron meddelandekö

Broker-stöd är inaktiverat som standard. Du aktiverar den för en enskild PublicClientApplication klass. Använd parametern WithBroker() när du skapar PublicClientApplication klassen via PublicClientApplicationBuilder. Parametern WithBroker() är inställd på true som standard.

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

Steg 2: Uppdatera AppDelegate för att hantera återanropet

När MSAL.NET anropar asynkron meddelandekö anropar mäklaren sedan tillbaka till ditt program. Den anropar tillbaka med hjälp AppDelegate.OpenUrl av metoden . Eftersom MSAL väntar på svaret från mäklaren måste ditt program samarbeta för att anropa MSAL.NET tillbaka. Du konfigurerar det här beteendet genom att uppdatera AppDelegate.cs filen för att åsidosätta metoden, som följande kod visar.

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

Den här metoden anropas varje gång programmet startas. Det är en möjlighet att bearbeta svaret från asynkron meddelandekö och slutföra autentiseringsprocessen som MSAL.NET startat.

Steg 3: Ange ett UIViewController()

För Xamarin iOS behöver du normalt inte ange ett objektfönster. Men i det här fallet bör du ange det så att du kan skicka och ta emot svar från en mäklare. Om du vill ange ett objektfönster i AppDelegate.csanger du en ViewController.

Följ dessa steg för att ange objektfönstret:

I AppDelegate.csanger du App.RootViewController till en ny UIViewController(). Den här inställningen säkerställer att anropet till asynkron meddelandekö innehåller UIViewController. Om den inte är korrekt inställd kan du få det här felet:

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

I anropet AcquireTokenInteractive använder du .WithParentActivityOrWindow(App.RootViewController). Skicka in referensen till det objektfönster som du ska använda. Här är ett exempel:

I App.cs:

   public static object RootViewController { get; set; }

I AppDelegate.cs:

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

I anropet AcquireToken :

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

Steg 4: Registrera ett URL-schema

MSAL.NET använder URL:er för att anropa asynkron meddelandekö och sedan returnera koordinatorsvaret tillbaka till din app. Slutför rundturen genom att registrera appens URL-schema i Info.plist filen.

Följ dessa steg för att registrera appens URL-schema:

Prefix CFBundleURLSchemes med msauth.

Lägg till CFBundleURLName i slutet. Följ det här mönstret:

$"msauth.(BundleId)"

BundleId Här identifierar enheten unikt. Om är är yourcompany.xformsmsauth.com.yourcompany.xformsditt URL-schema till exempel BundleId .

Det här URL-schemat blir en del av omdirigerings-URI:n som unikt identifierar din app när den tar emot koordinatorns svar.

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

Steg 5: Lägg till i avsnittet LSApplicationQueriesSchemes

MSAL använder –canOpenURL: för att kontrollera om asynkron meddelandekö är installerad på enheten. I iOS 9 låste Apple de scheman som ett program kan fråga efter.

Lägg till msauthv2 i LSApplicationQueriesSchemes avsnittet i Info.plist filen, som i följande kodexempel:

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

Asynkron autentisering för MSAL för iOS och macOS

Asynkron autentisering är aktiverat som standard för Microsoft Entra-scenarier.

Steg 1: Uppdatera AppDelegate för att hantera återanropet

När MSAL för iOS och macOS anropar asynkron meddelandekö anropar mäklaren tillbaka till ditt program med hjälp openURL av metoden . Eftersom MSAL väntar på svaret från asynkron meddelandekö måste ditt program samarbeta för att anropa MSAL. Konfigurera den här funktionen genom att uppdatera AppDelegate.m filen för att åsidosätta metoden, som följande kodexempel visar.

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

Om du har antagit UISceneDelegate i iOS 13 eller senare placerar du MSAL-återanropet scene:openURLContexts: UISceneDelegate i stället för. MSAL handleMSALResponse:sourceApplication: får bara anropas en gång för varje URL.

Mer information finns i Apple-dokumentationen.

Steg 2: Registrera ett URL-schema

MSAL för iOS och macOS använder URL:er för att anropa asynkron meddelandekö och returnera sedan koordinatorsvaret till din app. Slutför rundturen genom att registrera ett URL-schema för din app i Info.plist filen.

Så här registrerar du ett schema för din app:

Prefixa ditt anpassade URL-schema med msauth.
Lägg till paketidentifieraren i slutet av schemat. Följ det här mönstret:

$"msauth.(BundleId)"

BundleId Här identifierar enheten unikt. Om är är yourcompany.xformsmsauth.com.yourcompany.xformsditt URL-schema till exempel BundleId .

Det här URL-schemat blir en del av omdirigerings-URI:n som unikt identifierar din app när den tar emot koordinatorns svar. Kontrollera att omdirigerings-URI:n i formatet msauth.(BundleId)://auth är registrerad för ditt program.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Steg 3: Lägg till LSApplicationQueriesSchemes

Lägg till LSApplicationQueriesSchemes för att tillåta anrop till Microsoft Authenticator-appen om den är installerad.

Kommentar

Schemat msauthv3 behövs när appen kompileras med Xcode 11 och senare.

Här är ett exempel på hur du lägger LSApplicationQueriesSchemestill :

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

Asynkron autentisering för Xamarin.Android

Information om hur du aktiverar en koordinator på Android finns i Asynkron autentisering på Xamarin.Android.

Nästa steg

Gå vidare till nästa artikel i det här scenariot, Hämta en token.

Dela via

Konfigurera en mobilapp som anropar webb-API:er

Microsoft-bibliotek som stöder mobilappar

Instansiera programmet

Android

iOS

Xamarin eller UWP

Instansiera programmet

Ange det överordnade användargränssnittet, fönstret eller aktiviteten

Hitta fler appbyggparametrar

Uppgifter för MSAL för iOS och macOS

Uppgifter för Xamarin.Android

Uppgifter för UWP

Konfigurera programmet så att det använder asynkron meddelandekö

Aktivera asynkron meddelandekö på Xamarin

Aktivera asynkron meddelandekö för MSAL för Android

Aktivera asynkron meddelandekö för MSAL för iOS och macOS

Aktivera asynkron autentisering för Xamarin iOS

Steg 1: Aktivera stöd för asynkron meddelandekö

Steg 2: Uppdatera AppDelegate för att hantera återanropet

Steg 3: Ange ett UIViewController()

Steg 4: Registrera ett URL-schema

Steg 5: Lägg till i avsnittet LSApplicationQueriesSchemes

Asynkron autentisering för MSAL för iOS och macOS

Steg 1: Uppdatera AppDelegate för att hantera återanropet

Steg 2: Registrera ett URL-schema

Steg 3: Lägg till LSApplicationQueriesSchemes

Asynkron autentisering för Xamarin.Android

Nästa steg

Feedback

Ytterligare resurser