Leitfaden für die Migration von ADAL zu MSAL für Android

In diesem Artikel werden änderungen erläutert, die Sie zum Migrieren einer App vornehmen müssen, die die Azure Active Directory Authentication Library (ADAL) verwendet, um die Microsoft Authentication Library (MSAL) (MSAL) zu verwenden.

Hervorhebungen von Unterschieden

ADAL funktioniert mit dem Azure AD v1.0-Endpunkt. Die Microsoft Authentication Library (MSAL) (MSAL) arbeitet mit der Microsoft-Identitätsplattform, früher bekannt als der Azure AD v2.0-Endpunkt. Die Microsoft Identity Platform unterscheidet sich von Azure AD v1.0 darin:

Unterstützt:

• Organisationsidentität (Microsoft Entra ID)

• Nicht organisatorische Identitäten wie Outlook.com, Xbox Live usw.

• (nur Azure AD B2C) Verbundanmeldung mit Google, Facebook, X und Amazon

• Ist Standards kompatibel mit:

  • OAuth v2.0
  • OpenID Connect (OIDC)

Die öffentliche MSAL-API führt wichtige Änderungen ein, darunter:

• Ein neues Modell für den Zugriff auf Token:
  • ADAL ermöglicht den Zugriff auf Token über AuthenticationContext, das den Server repräsentiert. MSAL bietet über das PublicClientApplication, das den Client darstellt, Zugriff auf Token. Cliententwickler müssen keine neue PublicClientApplication Instanz für jede Autorität erstellen, mit der sie interagieren müssen. Es ist nur eine PublicClientApplication Konfiguration erforderlich.
  • Unterstützung für das Anfordern von Zugriffstoken mithilfe von Bereichsangaben neben Ressourcenbezeichnern.
  • Unterstützung für inkrementelle Zustimmung. Entwickler können Bereiche anfordern, wenn der Benutzer auf mehr und mehr Funktionen in der App zugreift, einschließlich derer, die während der App-Registrierung nicht enthalten sind.
  • Autoritative Stellen werden nicht mehr zur Runtime überprüft. Stattdessen erklärt der Entwickler während der Entwicklung eine Liste der "bekannten Behörden".
• Token-API-Änderungen:
  • In ADAL wird AcquireToken() zunächst eine stille Anfrage gestellt. Falls das fehlschlägt, wird eine interaktive Anfrage ausgeführt. Dieses Verhalten führte dazu, dass einige Entwickler nur darauf AcquireTokenvertrauen, was dazu führte, dass der Benutzer zu bestimmten Zeiten unerwartet zur Eingabe von Anmeldeinformationen aufgefordert wurde. MSAL verlangt von Entwicklern, bewusst festzulegen, wann der Benutzer eine UI-Aufforderung erhält.
    • AcquireTokenSilent führt immer zu einer stillen Anforderung, die entweder erfolgreich ist oder fehlschlägt.
    • AcquireToken führt immer zu einer Anforderung, die den Benutzer über die Benutzeroberfläche auffordert.
• MSAL unterstützt die Anmeldung über einen Standardbrowser oder eine eingebettete Webansicht:
  • Standardmäßig wird der Standardbrowser auf dem Gerät verwendet. Dadurch kann MSAL den Authentifizierungsstatus (Cookies) verwenden, der möglicherweise bereits für ein oder mehrere angemeldete Konten vorhanden ist. Wenn kein Authentifizierungsstatus vorhanden ist, führt die Authentifizierung während der Autorisierung über MSAL dazu, dass der Authentifizierungsstatus (Cookies) für andere Webanwendungen erstellt wird, die im selben Browser verwendet werden.
• Neues Ausnahmemodell:
  • Ausnahmen definieren den Typ des aufgetretenen Fehlers deutlicher und was der Entwickler tun muss, um ihn zu beheben.
• MSAL unterstützt Parameterobjekte für AcquireToken und AcquireTokenSilent Aufrufe.
• MSAL unterstützt deklarative Konfiguration für:
  • Client-ID, Umleitungs-URI.
  • Eingebettet vs. Standardbrowser
  • Behörden
  • HTTP-Einstellungen wie Lese- und Verbindungstimeout

Ihre App-Registrierung und Migration zu MSAL

Sie müssen Ihre vorhandene App-Registrierung nicht ändern, um MSAL zu verwenden. Wenn Sie die inkrementelle/progressive Zustimmung nutzen möchten, müssen Sie die Registrierung möglicherweise überprüfen, um die spezifischen Bereiche zu identifizieren, die Sie inkrementell anfordern möchten. Weitere Informationen zu Berechtigungsumfängen und der inkrementellen Einwilligung folgen.

In Ihrer App-Registrierung im Portal wird eine Registerkarte "API-Berechtigungen " angezeigt. Dadurch wird eine Liste der APIs und Berechtigungen (Bereiche) bereitgestellt, auf die Ihre App derzeit konfiguriert ist, um den Zugriff anzufordern. Außerdem wird eine Liste der Bereichsnamen angezeigt, die den einzelnen API-Berechtigungen zugeordnet sind.

Benutzerzustimmung

Mit ADAL und dem Azure AD v1.0-Endpunkt wurde dem Benutzer die Zustimmung zu Ressourcen erteilt, die er besitzt, bei der ersten Verwendung. Mit MSAL und dem Microsoft Identity Platform kann die Zustimmung inkrementell angefordert werden. Die inkrementelle Zustimmung ist nützlich für Berechtigungen, die ein Benutzer als hohe Berechtigungen in Betracht ziehen kann, oder kann andernfalls fragen, ob die Berechtigung nicht mit einer klaren Erläuterung bereitgestellt wird, warum die Berechtigung erforderlich ist. In ADAL haben diese Berechtigungen möglicherweise dazu geführt, dass der Benutzer die Anmeldung bei Ihrer App abgebrochen hat.

Administratorzustimmung

Organisationsadministratoren können berechtigungen zustimmen, die Ihre Anwendung im Namen aller Mitglieder ihrer Organisation erfordert. Einige Organisationen erlauben administratoren nur, Anwendungen zuzustimmen. Die Administratorzustimmung erfordert, dass Sie alle API-Berechtigungen und Bereiche einschließen, die von Ihrer Anwendung in Ihrer App-Registrierung verwendet werden.

Migration von Ressourcen-IDs zu Scopes

Authentifizieren und Anfordern der Autorisierung für alle Berechtigungen bei der ersten Verwendung

Wenn Sie derzeit ADAL verwenden und keine inkrementelle Zustimmung verwenden müssen, besteht die einfachste Möglichkeit, MSAL zu verwenden, darin, eine acquireToken Anforderung mithilfe des neuen AcquireTokenParameter Objekts zu stellen und den Ressourcen-ID-Wert festzulegen.

Dies führt zum gleichen v1-Verhalten, an das Sie gewöhnt sind. Alle berechtigungen, die in Ihrer App-Registrierung angefordert werden, werden während der ersten Interaktion vom Benutzer angefordert.

Authentifizieren und Anfordern von Berechtigungen nur nach Bedarf

Um die inkrementelle Zustimmung zu nutzen, erstellen Sie eine Liste der Berechtigungen (Bereiche), die Ihre App aus Ihrer App-Registrierung verwendet, und ordnen Sie sie in zwei Listen auf der Grundlage:

• Welche Berechtigungsbereiche Sie während der ersten Interaktion des Nutzers mit Ihrer App während der Anmeldung anfordern möchten.
• Die Berechtigungen, die einem wichtigen Feature Ihrer App zugeordnet sind, müssen Sie dem Benutzer auch erklären.

Nachdem Sie die Bereiche organisiert haben, ordnen Sie jede Liste an, für welche Ressource (API) Sie ein Token anfordern möchten. Sowie alle anderen Berechtigungsumfänge, die der Benutzer gleichzeitig autorisieren soll.

Das Parameterobjekt, das verwendet wird, um Ihre Anforderung an MSAL zu senden, unterstützt:

• Scope: Die Liste der Bereiche, für die Sie die Autorisierung anfordern und ein Zugriffstoken empfangen möchten.
• ExtraScopesToConsent: Eine zusätzliche Liste der Bereiche, für die Sie die Autorisierung anfordern möchten, während Sie ein Zugriffstoken für eine andere Ressource anfordern. Diese Liste der Bereiche ermöglicht es Ihnen, die Anzahl der Male zu minimieren, die Sie zum Anfordern der Benutzerautorisierung benötigen. Das bedeutet weniger Benutzerautorisierungs- oder Zustimmungsaufforderungen.

Migrieren von AuthenticationContext zu PublicClientApplications

Erstellen von PublicClientApplication

Wenn Sie MSAL verwenden, instanziieren Sie ein PublicClientApplication. Dieses Objekt modelliert Ihre App-Identität und wird verwendet, um Anforderungen an eine oder mehrere Behörden zu stellen. Mit diesem Objekt konfigurieren Sie Ihre Clientidentität, umleitungs-URI, Standardautorität, ob der Gerätebrowser im Vergleich zur eingebetteten Webansicht, der Protokollebene und mehr verwendet werden soll.

Sie können dieses Objekt deklarativ mit JSON konfigurieren, das Sie entweder als Datei bereitstellen oder als Ressource innerhalb Ihrer APK speichern.

Obwohl es sich bei diesem Objekt nicht um ein Singleton handelt, verwendet es intern für interaktive wie auch stille Anforderungen ein gemeinsames Executors.

Unternehmen zu Unternehmen

In ADAL erfordert jede Organisation, von der Sie Zugriffstoken anfordern, eine separate Instanz der AuthenticationContext. In MSAL ist dies keine Anforderung mehr. Sie können die Autorisierungsstelle, von der Sie ein Token anfordern möchten, als Teil Ihrer stillen oder interaktiven Anfrage angeben.

Migration von der Autoritätsüberprüfung zu bekannten autoritativen Stellen

MSAL verfügt nicht über ein Flag zum Aktivieren oder Deaktivieren der Autoritätsüberprüfung. Die Autoritätsüberprüfung ist ein Feature in ADAL und in den frühen Versionen von MSAL, das verhindert, dass Ihr Code Token von einer potenziell böswilligen Autorität anfordert. MSAL ruft nun eine Liste der Behörden ab, die Microsoft bekannt sind, und führt diese Liste mit den Behörden zusammen, die Sie in Ihrer Konfiguration angegeben haben.

Wenn Sie versuchen, eine Autorität zu verwenden, die für Microsoft nicht bekannt ist und nicht in Ihrer Konfiguration enthalten ist, erhalten Sie eine UnknownAuthorityException.

Protokollierung

Sie können jetzt die Protokollierung als Teil Ihrer Konfiguration deklarativ konfigurieren, wie folgt:

"logging": {
  "pii_enabled": false,
  "log_level": "WARNING",
  "logcat_enabled": true
}

Migrieren von UserInfo zu Konto

In ADAL stellt das AuthenticationResult Objekt ein UserInfo Objekt bereit, das zum Abrufen von Informationen über das authentifizierte Konto verwendet wird. Der Begriff "Benutzer", der einen menschlichen oder Software-Agent bedeutete, wurde auf eine Weise angewendet, die es schwierig machte, zu kommunizieren, dass einige Apps einen einzelnen Benutzer (ob ein menschlichen oder Software-Agent) unterstützen, der mehrere Konten hat.

Erwägen Sie ein Bankkonto. Möglicherweise haben Sie mehr als ein Konto bei mehr als einem Finanzinstitut. Wenn Sie ein Konto eröffnen, erhalten Sie (der Nutzer) Zugangsdaten, z. B. eine Bankkarte und eine PIN, die für den Zugriff auf Ihren Kontostand, Rechnungszahlungen usw. für jedes Konto verwendet werden. Diese Anmeldeinformationen können nur beim Finanzinstitut verwendet werden, das sie ausgestellt hat.

Ähnlich wie bei Konten bei einem Finanzinstitut greift man auch bei Konten in der Microsoft Identity Platform mithilfe von Anmeldeinformationen zu. Diese Anmeldeinformationen sind entweder bei Microsoft registriert oder wurden von Microsoft ausgestellt. Oder durch Microsoft im Namen einer Organisation.

Wo sich die Microsoft Identity Platform von einem Finanzinstitut unterscheidet, besteht in dieser Analogie darin, dass die Microsoft Identity Platform ein Framework bereitstellt, das es einem Benutzer ermöglicht, ein Konto und seine zugehörigen Anmeldeinformationen zu verwenden, um auf Ressourcen zuzugreifen, die mehreren Einzelpersonen und Organisationen angehören. Dies ist wie die Möglichkeit, eine von einer Bank ausgestellte Karte an einem anderen Finanzinstitut zu verwenden. Dies funktioniert, da alle betreffenden Organisationen die Microsoft Identity Platform verwenden, wodurch ein Konto in mehreren Organisationen verwendet werden kann. Im Folgenden finden Sie ein Beispiel:

Sam arbeitet für Contoso.com, verwaltet aber Azure virtuellen Computer, die zu Fabrikam.com gehören. Damit Sam die virtuellen Computer von Fabrikam verwalten kann, muss er berechtigt sein, auf sie zuzugreifen. Dieser Zugriff kann gewährt werden, indem Sams Konto zu Fabrikam.com hinzugefügt und seinem Konto eine Rolle gewährt wird, die es ihm ermöglicht, mit den virtuellen Computern zu arbeiten. Dies geschieht mit dem Azure Portal.

Das Hinzufügen des Contoso.com-Kontos von Sam als Mitglied von Fabrikam.com würde dazu führen, dass ein neuer Datensatz für Sam in der Microsoft Entra-ID von Fabrikam.com erstellt wird. Sams Datensatz in Microsoft Entra ID wird als Benutzerobjekt bezeichnet. In diesem Fall würde dieses Benutzerobjekt in Contoso.com auf das Benutzerobjekt von Sam verweisen. Sams Fabrikam-Benutzerobjekt ist die lokale Darstellung von Sam und wird verwendet, um Informationen über das Konto zu speichern, das Sam im Kontext von Fabrikam.com zugeordnet ist. In Contoso.com ist Sams Titel Senior DevOps Consultant. Bei Fabrikam hat Sam den Titel Auftragnehmer für virtuelle Maschinen. In Contoso.com ist Sam nicht verantwortlich oder autorisiert, virtuelle Computer zu verwalten. In Fabrikam.com ist das seine einzige Funktion. Sam verfügt jedoch immer noch nur über einen Satz Anmeldeinformationen, den er verwalten muss, nämlich die von Contoso.com ausgestellten Anmeldeinformationen.

Sobald ein erfolgreicher acquireToken Aufruf erfolgt ist, wird ein Verweis auf ein IAccount Objekt angezeigt, das in späteren acquireTokenSilent Anforderungen verwendet werden kann.

IMultiTenantAccount

Wenn Sie eine App haben, die von jedem Mandanten, in dem das Konto dargestellt wird, auf die das Konto betreffende Ansprüche zugreift, können Sie IAccount-Objekte in IMultiTenantAccount umwandeln. Diese Schnittstelle stellt eine Zuordnung von ITenantProfiles (nach Mandanten-ID) dar, mit der Sie in den einzelnen Mandanten, von denen Sie ein Token angefordert haben, auf die Ansprüche zugreifen können, die zu dem Konto gehören (relativ zum aktuellen Konto).

Die Ansprüche im Stamm von IAccount und IMultiTenantAccount enthalten immer die Ansprüche vom Home-Mandanten. Wenn Sie noch keine Anforderung für ein Token im Home-Mandanten erstellt haben, ist diese Sammlung leer.

Weitere Änderungen

Verwenden Sie den neuen AuthenticationCallback

// Existing ADAL Interface
public interface AuthenticationCallback<T> {

    /**
     * This will have the token info.
     *
     * @param result returns <T>
     */
    void onSuccess(T result);

    /**
     * Sends error information. This can be user related error or server error.
     * Cancellation error is AuthenticationCancelError.
     *
     * @param exc return {@link Exception}
     */
    void onError(Exception exc);
}

// New Interface for Interactive AcquireToken
public interface AuthenticationCallback {

    /**
     * Authentication finishes successfully.
     *
     * @param authenticationResult {@link IAuthenticationResult} that contains the success response.
     */
    void onSuccess(final IAuthenticationResult authenticationResult);

    /**
     * Error occurs during the authentication.
     *
     * @param exception The {@link MsalException} contains the error code, error message and cause if applicable. The exception
     *                  returned in the callback could be {@link MsalClientException}, {@link MsalServiceException}
     */
    void onError(final MsalException exception);

    /**
     * Will be called if user cancels the flow.
     */
    void onCancel();
}

// New Interface for Silent AcquireToken
public interface SilentAuthenticationCallback {

    /**
     * Authentication finishes successfully.
     *
     * @param authenticationResult {@link IAuthenticationResult} that contains the success response.
     */
    void onSuccess(final IAuthenticationResult authenticationResult);

    /**
     * Error occurs during the authentication.
     *
     * @param exception The {@link MsalException} contains the error code, error message and cause if applicable. The exception
     *                  returned in the callback could be {@link MsalClientException}, {@link MsalServiceException} or
     *                  {@link MsalUiRequiredException}.
     */
    void onError(final MsalException exception);
}

Zu den neuen Ausnahmen migrieren

In ADAL gibt es einen Ausnahmetyp, AuthenticationExceptionder eine Methode zum Abrufen des ADALError Enumerationswerts enthält. In MSAL gibt es eine Hierarchie von Ausnahmen, und jeder verfügt über einen eigenen Satz von zugeordneten spezifischen Fehlercodes.

ADALError zu MsalException-Übersetzung

ADAL-Protokollierung zu MSAL-Protokollierung

// Legacy Interface
    StringBuilder logs = new StringBuilder();
    Logger.getInstance().setExternalLogger(new ILogger() {
            @Override
            public void Log(String tag, String message, String additionalMessage, LogLevel logLevel, ADALError errorCode) {
                logs.append(message).append('\n');
            }
        });

// New interface
  StringBuilder logs = new StringBuilder();
  Logger.getInstance().setExternalLogger(new ILoggerCallback() {
      @Override
      public void log(String tag, Logger.LogLevel logLevel, String message, boolean containsPII) {
          logs.append(message).append('\n');
      }
  });

// New Log Levels:
public enum LogLevel
{
    /**
     * Error level logging.
     */
    ERROR,
    /**
     * Warning level logging.
     */
    WARNING,
    /**
     * Info level logging.
     */
    INFO,
    /**
     * Verbose level logging.
     */
    VERBOSE
}