Lernprogramm: Vorbereiten Ihrer iOS-App (Swift) für die Authentifizierung

Dies ist das zweite Lernprogramm in der Lernprogrammreihe, das veranschaulicht, wie Sie Microsoft Authentication Library (MSAL) für iOS und macOS zu Ihrer iOS Swift-App hinzufügen.

Bevor Sie beginnen, verwenden Sie den Selektor Mandantentyp auswählen oben auf dieser Seite, um den Mandantentyp auszuwählen. Die Microsoft Entra-ID stellt zwei Mandantenkonfigurationen, Mitarbeiter und externe Konfigurationen bereit. Eine konfiguration für einen Mitarbeitermandanten richtet sich an Ihre Mitarbeiter, interne Apps und andere Organisationsressourcen. Ein externer Mandant richtet sich an Ihre kundenorientierten Apps.

In diesem Tutorial führen Sie Folgendes durch:

Voraussetzungen

• Registrieren Sie eine neue Clientweb-App im Microsoft Entra Admin Center, die für Konten in einem beliebigen Organisationsverzeichnis und persönlichen Microsoft-Konten konfiguriert ist. Weitere Informationen finden Sie unter Registrieren einer Anwendung . Notieren Sie die folgenden Werte auf der Anwendungsübersichtsseite für die spätere Verwendung:
  • Anwendungs-ID (Client)
  • Verzeichnis-ID (Mandant)
• Xcode.
• iOS(Swift)-Projekt.

Hinzufügen einer Plattformumleitungs-URL

Führen Sie die folgenden Schritte aus, um ihren App-Typ für ihre App-Registrierung anzugeben:

1. Wählen Sie unter Verwalten die Optionen Authentifizierung>Plattform hinzufügen>iOS/macOS aus.
2. Geben Sie die Bündel-ID Ihres Projekts ein. Wenn das Codebeispiel heruntergeladen wurde, lautet die Bundle-ID com.microsoft.identitysample.MSALiOS. Wählen Sie bei der Erstellung eines eigenen Projekts Ihr Projekt in Xcode aus, und öffnen Sie die Registerkarte General (Allgemein). Die Paket-ID wird im Abschnitt Identity (Identität) angezeigt.
3. Wählen Sie Konfigurieren aus, und speichern Sie die MSAL-Konfiguration, die auf der Seite MSAL-Konfiguration angezeigt wird, damit Sie diese später beim Konfigurieren Ihrer App eingeben können.
4. Wählen Sie Fertig aus.

Hinzufügen des MSAL-Frameworks zu einer iOS-App (Swift)

Wählen Sie eine der folgenden Methoden, um die MSAL-Bibliothek in Ihrer App zu installieren:

CocoaPods

1. Wenn Sie CocoaPods verwenden, installieren Sie MSAL. Erstellen Sie dazu zunächst in dem Ordner, in dem sich auch die Datei .xcodeproj Ihres Projekts befindet, eine leere Datei namens podfile. Fügen Sie der Datei podfile Folgendes hinzu:

   use_frameworks!
   
   target '<your-target-here>' do
      pod 'MSAL'
   end
   

2. Ersetzen Sie <your-target-here> durch den Namen Ihres Projekts.

3. Navigieren Sie in einem Terminalfenster zu dem Ordner, der die erstellte Datei podfile enthält, und führen Sie pod install zum Installieren der MSAL-Bibliothek aus.

4. Schließen Sie Xcode, und öffnen Sie <your project name>.xcworkspace, um das Projekt erneut in Xcode zu laden.

Karthago

Wenn Sie Carthage verwenden, installieren Sie MSAL, indem Sie es zu Ihrer Cartfile hinzufügen.

github "AzureAD/microsoft-authentication-library-for-objc" "master"

Führen Sie in dem Verzeichnis, in dem sich auch die aktualisierte Cartfile-Datei befindet, in einem Terminalfenster den folgenden Befehl aus, damit Carthage die Abhängigkeiten in Ihrem Projekt aktualisiert.

Ios:

carthage update --platform iOS

macOS:

carthage update --platform macOS

Manuell

Sie können auch ein Git-Submodul oder das neueste Release als Framework in Ihrer Anwendung verwenden.

Die App-Registrierung hinzufügen

Im nächsten Schritt fügen Sie die App-Registrierung zu Ihrem Code hinzu.

Fügen Sie zuerst die folgende Importanweisung oben in der Datei ViewController.swift und entweder in der AppDelegate.swift oder in der SceneDelegate.swift hinzu:

import MSAL

Fügen Sie als Nächstes den folgenden Code zu ViewController.swift vor viewDidLoad() hinzu:

// Update the below to your client ID. The below is for running the demo only
let kClientID = "Your_Application_Id_Here"
let kGraphEndpoint = "https://graph.microsoft.com/" // the Microsoft Graph endpoint
let kAuthority = "https://login.microsoftonline.com/common" // this authority allows a personal Microsoft account and a work or school account in any organization's Azure AD tenant to sign in

let kScopes: [String] = ["user.read"] // request permission to read the profile of the signed-in user

var accessToken = String()
var applicationContext : MSALPublicClientApplication?
var webViewParameters : MSALWebviewParameters?
var currentAccount: MSALAccount?

Sie ändern nur den Wert, der kClientID als Anwendungs-ID zugewiesen wird. Dieser Wert ist Teil der MSAL-Konfigurationsdaten, die Sie am Anfang dieses Tutorials zum Registrieren der Anwendung gespeichert haben.

Erstellen einer SDK-Instanz

Führen Sie die folgenden Schritte aus, um eine MSAL-Instanz in Ihrem Projekt zu erstellen:

Fügen Sie der Klasse ViewController die Methode initMSAL hinzu:

    func initMSAL() throws {

        guard let authorityURL = URL(string: kAuthority) else {
            self.updateLogging(text: "Unable to create authority URL")
            return
        }

        let authority = try MSALAADAuthority(url: authorityURL)

        let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
        self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
        self.initWebViewParams()
    }

Fügen Sie weiterhin in der Klasse ViewController und nach der Methode initMSAL die Methode initWebViewParams hinzu:

iOS-Code:

func initWebViewParams() {
        self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
    }

macOS-Code:

func initWebViewParams() {
        self.webViewParameters = MSALWebviewParameters()
    }

Konfigurieren von Xcode-Projekteinstellungen

Fügen Sie Signierung und Funktionen Ihres Projekts eine neue Keychaingruppe hinzu. Die Keychaingruppe sollte unter iOS com.microsoft.adalcache und unter macOS com.microsoft.identity.universalstorage lauten.

Nur für iOS: URL-Schemas konfigurieren

In diesem Schritt registrieren Sie CFBundleURLSchemes, damit der Benutzer nach der Anmeldung zurück zur App geleitet werden kann. LSApplicationQueriesSchemes ermöglicht Ihrer App darüber hinaus die Verwendung von Microsoft Authenticator.

Öffnen Sie in Xcode Info.plist als Quellcodedatei, und fügen Sie im Abschnitt <dict> Folgendes hinzu. Ersetzen Sie [BUNDLE_ID] durch den Wert, den Sie zuvor verwendet haben. Wenn Sie den Code heruntergeladen haben, lautet die Bundle-ID com.microsoft.identitysample.MSALiOS. Wählen Sie bei der Erstellung eines eigenen Projekts Ihr Projekt in Xcode aus, und öffnen Sie die Registerkarte General (Allgemein). Die Paket-ID wird im Abschnitt Identity (Identität) angezeigt.

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>msauthv2</string>
    <string>msauthv3</string>
</array>

Nur macOS: Konfigurieren der App-Sandbox

1. Navigieren Sie zu „Xcode Projekteinstellungen“ >Registerkarte „Funktionen“>App-Sandbox.
2. Aktivieren Sie das Kontrollkästchen Ausgehende Verbindungen (Client).

Nächste Schritte

Dies ist das zweite Lernprogramm in der Lernprogrammreihe, das veranschaulicht, wie Sie Microsoft Authentication Library (MSAL) für iOS und macOS zu Ihrer iOS Swift-App hinzufügen.

Bevor Sie beginnen, verwenden Sie den Selektor Mandantentyp auswählen oben auf dieser Seite, um den Mandantentyp auszuwählen. Die Microsoft Entra-ID stellt zwei Mandantenkonfigurationen, Mitarbeiter und externe Konfigurationen bereit. Eine konfiguration für einen Mitarbeitermandanten richtet sich an Ihre Mitarbeiter, interne Apps und andere Organisationsressourcen. Ein externer Mandant richtet sich an Ihre kundenorientierten Apps.

In diesem Tutorial führen Sie Folgendes durch:

Voraussetzungen

• Registrieren Sie eine neue Clientweb-App im Microsoft Entra Admin Center, die für Konten in einem beliebigen Organisationsverzeichnis und persönlichen Microsoft-Konten konfiguriert ist. Weitere Informationen finden Sie unter Registrieren einer Anwendung . Notieren Sie die folgenden Werte auf der Anwendungsübersichtsseite für die spätere Verwendung:
  • Anwendungs-ID (Client)
  • Verzeichnis-ID (Mandant)
• Xcode.
• iOS(Swift)-Projekt.

Hinzufügen einer Plattformumleitungs-URL

Führen Sie die folgenden Schritte aus, um ihren App-Typ für ihre App-Registrierung anzugeben:

1. Wählen Sie unter Verwalten die Optionen Authentifizierung>Plattform hinzufügen>iOS/macOS aus.
2. Geben Sie die Bündel-ID Ihres Projekts ein. Wenn das Codebeispiel heruntergeladen wurde, lautet die Bundle-ID com.microsoft.identitysample.MSALiOS. Wählen Sie bei der Erstellung eines eigenen Projekts Ihr Projekt in Xcode aus, und öffnen Sie die Registerkarte General (Allgemein). Die Paket-ID wird im Abschnitt Identity (Identität) angezeigt.
3. Wählen Sie Konfigurieren aus, und speichern Sie die MSAL-Konfiguration, die auf der Seite MSAL-Konfiguration angezeigt wird, damit Sie diese später beim Konfigurieren Ihrer App eingeben können.
4. Wählen Sie Fertig aus.

Aktivieren des öffentlichen Clientflows

Führen Sie diese Schritte aus, um Ihre App als öffentlichen Client zu identifizieren:

1. Wählen Sie unter Verwalten die Option Authentifizierung aus.

2. Wählen Sie unter Erweiterte Einstellungen für Öffentliche Clientflows zulassen die Option Ja aus.

3. Wählen Sie Speichern aus, um Ihre Änderungen zu speichern.

Hinzufügen des MSAL-Frameworks zu einer iOS-App (Swift)

Das MSAL-Authentifizierungs-SDK wird für die Integration der Authentifizierung in Ihre Apps mithilfe von OAuth2 und OpenID Connect verwendet. Sie können Benutzer oder Apps mit Microsoft-Identitäten anmelden. Führen Sie die folgenden Schritte aus, um IHREM iOS-Projekt (Swift) MSAL hinzuzufügen:

1. Öffnen Sie Ihr iOS-Projekt in Xcode.
2. Wählen Sie im Menü "Datei" die Option "Paketabhängigkeiten hinzufügen" aus.
3. Geben Sie https://github.com/AzureAD/microsoft-authentication-library-for-objc als Paket-URL ein, und wählen Sie "Paket hinzufügen" aus.

Aktualisieren des Bundle-Identifiers

Im Apple-Ökosystem ist ein Bündelbezeichner ein eindeutiger Bezeichner für eine Anwendung. Führen Sie die folgenden Schritte aus, um den Bundlebezeichner in Ihrem Projekt zu aktualisieren:

1. Öffnen Sie die Projekteinstellungen. Geben Sie im Abschnitt Identity den Bundle Identifierein.

2. Klicken Sie mit der rechten Maustaste auf Info.plist, und wählen Sie Öffnen als>Quellcode aus.

3. Ersetzen Sie unter dem Stammknoten „dict“ Enter_the_bundle_Id_Here durch den Wert für Paket-ID, den Sie im Portal verwendet haben. Beachten Sie das Präfix msauth. in der Zeichenfolge.

   <key>CFBundleURLTypes</key>
   <array>
      <dict>
         <key>CFBundleURLSchemes</key>
         <array>
            <string>msauth.Enter_the_Bundle_Id_Here</string>
         </array>
      </dict>
   </array>
   

Erstellen einer SDK-Instanz

Führen Sie die folgenden Schritte aus, um eine MSAL-Instanz in Ihrem Projekt zu erstellen:

1. Importieren Sie die MSAL-Bibliothek in Ihren Ansichtscontroller, indem Sie import MSAL oben in der ViewController Klasse hinzufügen.

2. Fügen Sie ihrer ViewController-Klasse eine applicationContext Membervariable hinzu, indem Sie den folgenden Code direkt vor der viewDidLoad() Funktion hinzufügen:

   var applicationContext : MSALPublicClientApplication?
   var webViewParameters : MSALWebviewParameters?
   

   Der Code deklariert zwei Variablen: applicationContext, die eine Instanz von MSALPublicClientApplication, und webViewParameters, die eine Instanz von MSALWebviewParametersspeichert . MSALPublicClientApplication ist eine Klasse, die vom MSAL für die Behandlung von öffentlichen Clientanwendungen bereitgestellt wird. Dies MSALWebviewParameters ist eine Klasse von MSAL, die Parameter zum Konfigurieren der Webansicht definiert, die während des Authentifizierungsprozesses verwendet wird.

3. Fügen Sie der Ansichtsfunktion viewDidLoad() den folgenden Code hinzu:

    do {
           try self.initMSAL()
       } catch let error {
           self.updateLogging(text: "Unable to create Application Context \(error)")
       }
   

   Der Code versucht, MSAL zu initialisieren und alle Fehler zu behandeln, die während des Prozesses auftreten. Wenn ein Fehler auftritt, wird die Protokollierung mit den Details des Fehlers aktualisiert.

4. Fügen Sie den folgenden Code hinzu, der eine Funktion erstellt initMSAL() , die MSAL initialisiert:

       func initMSAL() throws {
   
       guard let authorityURL = URL(string: Configuration.kAuthority) else {
           self.updateLogging(text: "Unable to create authority URL")
           return
       }
   
       let authority = try MSALCIAMAuthority(url: authorityURL)
   
       let msalConfiguration = MSALPublicClientApplicationConfig(clientId: Configuration.kClientID,
                                                                 redirectUri: Configuration.kRedirectUri,
                                                                 authority: authority)
       self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
   }
   

   Dieser Code initialisiert msAL für iOS. Zunächst wird versucht, eine URL für die Autorität mithilfe der bereitgestellten Configuration.kAuthority-Zeichenfolge zu erstellen. Wenn die Methode erfolgreich verläuft, wird ein MSAL-Autoritätsobjekt basierend auf dieser URL erstellt. Anschließend wird MSALPublicClientApplication mit der angegebenen Client-ID, dem Umleitungs-URI und der Autorität konfiguriert. Wenn alle Konfigurationen ordnungsgemäß eingerichtet sind, initialisiert sie den Anwendungskontext mit dem konfigurierten MSALPublicClientApplication. Wenn während des Prozesses Fehler auftreten, wird eine Fehlermeldung ausgegeben.

5. Erstellen Sie die Datei "Configuration.swift ", und fügen Sie die folgenden Konfigurationen hinzu:

   import Foundation
   
   @objcMembers
   class Configuration {
       static let kTenantSubdomain = "Enter_the_Tenant_Subdomain_Here"
   
       // Update the below to your client ID you received in the portal.
       static let kClientID = "Enter_the_Application_Id_Here"
       static let kRedirectUri = "Enter_the_Redirect_URI_Here"
       static let kProtectedAPIEndpoint = "Enter_the_Protected_API_Full_URL_Here"
       static let kScopes = ["Enter_the_Protected_API_Scopes_Here"]
   
       static let kAuthority = "https://\(kTenantSubdomain).ciamlogin.com"
   
   }
   

   Dieser Swift-Konfigurationscode definiert eine Klasse mit dem Namen Configuration und wird mit @objcMembers gekennzeichnet. Sie enthält statische Konstanten für verschiedene Konfigurationsparameter im Zusammenhang mit einer Authentifizierungseinrichtung. Zu diesen Parametern gehören die Mandantendomäne, die Client-ID, der Umleitungs-URI, der geschützte API-Endpunkt und Bereiche. Diese Konfigurationskonstanten sollten mit den für das Setup der Anwendung spezifischen Werten aktualisiert werden.

   Suchen Sie den Platzhalter:

   • Enter_the_Application_Id_Here, und ersetzen Sie ihn mit der Anwendungs-ID (Client-ID) der zuvor von Ihnen registrierten Anwendung.
   • Enter_the_Redirect_URI_Here und ersetzen Sie ihn durch den Wert von kRedirectUri in der MSAL-Konfigurationsdatei, die Sie zuvor heruntergeladen haben, wenn Sie die Plattformumleitungs-URL hinzugefügt haben.
   • Enter_the_Protected_API_Scopes_Here, und ersetzen Sie dies durch die zuvor notierten Bereiche. Wenn Sie keine Bereiche aufgezeichnet haben, können Sie diese Bereichsliste leer lassen.
   • Enter_the_Tenant_Subdomain_Here und ersetzen Sie es durch die Verzeichnis-(Mandanten-)Unterdomäne. Wenn Ihre primäre Mandantendomäne z. B. contoso.onmicrosoft.comist, verwenden Sie contoso. Wenn Sie Ihre Mandantendomäne nicht kennen, erfahren Sie, wie Sie Ihre Mandantendetails lesen können.

Verwenden einer benutzerdefinierten URL-Domäne (optional)

Verwenden Sie eine benutzerdefinierte Domäne, um die Authentifizierungs-URL vollständig zu kennzeichnen. Aus Benutzerperspektive verbleiben Benutzer während des Authentifizierungsprozesses in Ihrer Domäne, anstatt zu ciamlogin.com Domänennamen umgeleitet zu werden.

Führen Sie die folgenden Schritte aus, um eine benutzerdefinierte Domäne zu verwenden:

1. Führen Sie die Schritte unter Aktivieren benutzerdefinierter URL-Domänen für Apps in externen Mandanten aus, um eine benutzerdefinierte URL-Domäne für Ihren externen Mandanten zu aktivieren.

2. Öffnen Sie die Datei "Configuration.swift ":

   1. Aktualisieren Sie den Wert der kAuthority Eigenschaft auf https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here. Ersetzen Sie sie Enter_the_Custom_Domain_Here durch Ihre benutzerdefinierte URL-Domäne und Enter_the_Tenant_ID_Here durch Ihre Mandanten-ID. Wenn Sie Ihre Mandanten-ID nicht kennen, finden Sie weitere Informationen unter Auslesen der Details Ihres Mandanten.

Nachdem Sie die Änderungen an Ihrer Datei "Configuration.swift " vorgenommen haben, wenn Ihre benutzerdefinierte URL-Domäne login.contoso.com ist und Ihre Mandanten-ID aaaabbbb-0000-cccc-1111-ddddd222eeeee ist, sollte Die Datei dem folgenden Codeausschnitt ähneln:

    import Foundation

    @objcMembers
    class Configuration {
        static let kTenantSubdomain = "login.contoso.com"
        
        // Update the below to your client ID you received in the portal.
        static let kClientID = "Enter_the_Application_Id_Here"
        static let kRedirectUri = "Enter_the_Redirect_URI_Here"
        static let kProtectedAPIEndpoint = "Enter_the_Protected_API_Full_URL_Here"
        static let kScopes = ["Enter_the_Protected_API_Scopes_Here"]
        
        static let kAuthority = "https://\(kTenantSubdomain)/aaaabbbb-0000-cccc-1111-dddd2222eeee"
    
    }

Nächste Schritte