Guida alla migrazione da ADAL a MSAL per Android

In questo articolo vengono evidenziate le modifiche necessarie per eseguire la migrazione di un'app che usa Azure Active Directory Authentication Library (ADAL) per usare il Libreria di Autenticazione Microsoft (MSAL).

Evidenziazioni delle differenze

ADAL funziona con l'endpoint Azure AD v1.0. Il Libreria di Autenticazione Microsoft (MSAL) funziona con il Microsoft Identity Platform, noto in precedenza come endpoint Azure AD v2.0. Il Microsoft Identity Platform differisce da Azure AD v1.0 in quanto:

Supporta:

• Identità organizzativa (Microsoft Entra ID)

• Identità non organizzative, ad esempio Outlook.com, Xbox Live e così via

• (solo Azure AD B2C) Accesso federato con Google, Facebook, X e Amazon

• Gli standard sono compatibili con:

  • OAuth v2.0
  • OpenID Connect (OIDC)

L'API pubblica MSAL introduce importanti modifiche, tra cui:

• Nuovo modello per l'accesso ai token:
  • ADAL fornisce l'accesso ai token tramite AuthenticationContext, che rappresenta il server. MSAL fornisce l'accesso ai token tramite PublicClientApplication, che rappresenta il client. Gli sviluppatori client non devono creare una nuova PublicClientApplication istanza per ogni autorità con cui devono interagire. È necessaria una PublicClientApplication sola configurazione.
  • Supporto per la richiesta di token di accesso tramite ambiti oltre agli identificatori di risorsa.
  • Supporto per il consenso incrementale. Gli sviluppatori possono richiedere ambiti man mano che l'utente accede a più funzionalità nell'app, incluse quelle non incluse durante la registrazione dell'app.
  • Le autorità non vengono più verificate in fase di esecuzione. Lo sviluppatore dichiara invece un elenco di "autorità note" durante lo sviluppo.
• Modifiche alle API dei token:
  • In ADAL, AcquireToken() effettua innanzitutto una richiesta non interattiva. In caso contrario, effettua una richiesta interattiva. Questo comportamento ha comportato che alcuni sviluppatori si basano solo su AcquireToken, il che ha comportato che l'utente venga richiesto in modo imprevisto per le credenziali in alcuni casi. MSAL richiede che gli sviluppatori decidano consapevolmente quando mostrare all'utente una richiesta dell'interfaccia utente.
    • AcquireTokenSilent comporta sempre una richiesta invisibile che o riesce o fallisce.
    • AcquireToken si traduce sempre in una richiesta che richiede l'intervento dell'utente tramite l'interfaccia utente.
• MSAL supporta l'accesso da un browser predefinito o da una visualizzazione Web incorporata:
  • Per impostazione predefinita, viene usato il browser predefinito nel dispositivo. Ciò consente a MSAL di usare lo stato di autenticazione (cookie) che potrebbe essere già presente per uno o più account connessi. Se non è presente alcuno stato di autenticazione, l'autenticazione durante l'autorizzazione tramite MSAL comporta la creazione dello stato di autenticazione (cookie) a vantaggio di altre applicazioni Web che verranno usate nello stesso browser.
• Nuovo modello di eccezione:
  • Le eccezioni definiscono in modo più chiaro il tipo di errore che si è verificato e cosa deve fare lo sviluppatore per risolverlo.
• MSAL supporta oggetti parametro per le chiamate AcquireToken e AcquireTokenSilent.
• MSAL supporta la configurazione dichiarativa per:
  • ID client, URI di reindirizzamento.
  • Browser incorporato e predefinito
  • Autorità
  • Impostazioni HTTP, ad esempio timeout di lettura e di connessione

Registrazione e migrazione dell'app a MSAL

Non è necessario modificare la registrazione dell'app esistente per usare MSAL. Per sfruttare i vantaggi del consenso incrementale/progressivo, potrebbe essere necessario esaminare la registrazione per identificare gli ambiti specifici da richiedere in modo incrementale. Altre informazioni sugli ambiti e sul consenso incrementale sono disponibili di seguito.

Nella registrazione dell'app nel portale verrà visualizzata una scheda Autorizzazioni API . Viene fornito un elenco delle API e delle autorizzazioni (ambiti) a cui l'app è attualmente configurata per richiedere l'accesso. Viene inoltre visualizzato un elenco dei nomi di ambito associati a ogni autorizzazione API.

Consenso dell'utente

Con ADAL e l'endpoint Azure AD v1.0, all'utente è stato concesso il consenso utente alle risorse di cui è proprietario al primo uso. Con MSAL e il Microsoft Identity Platform, il consenso può essere richiesto in modo incrementale. Il consenso incrementale è utile per le autorizzazioni che un utente può considerare privilegi elevati oppure può in caso contrario porre domande se non viene fornita una spiegazione chiara del motivo per cui è necessaria l'autorizzazione. In ADAL queste autorizzazioni potrebbero aver causato l'abbandono dell'accesso all'app da parte dell'utente.

Consenso dell'amministratore

Gli amministratori dell'organizzazione possono fornire il consenso alle autorizzazioni richieste dall'applicazione per conto di tutti i membri dell'organizzazione. Alcune organizzazioni consentono solo agli amministratori di fornire il consenso alle applicazioni. Il consenso dell'amministratore richiede l'inclusione di tutte le autorizzazioni API e gli ambiti usati dall'applicazione nella registrazione dell'app.

Migrazione da ID risorsa a ambiti

Autenticare e richiedere l'autorizzazione per tutte le autorizzazioni al primo utilizzo

Se attualmente si usa ADAL e non è necessario usare il consenso incrementale, il modo più semplice per iniziare a usare MSAL consiste nell'effettuare una acquireToken richiesta usando il nuovo AcquireTokenParameter oggetto e impostare il valore dell'ID risorsa.

Ciò comporterà lo stesso comportamento della versione v1 a cui sei abituato. Tutte le autorizzazioni richieste nella registrazione dell'app vengono richieste dall'utente durante la prima interazione.

Autenticare e richiedere autorizzazioni solo in base alle esigenze

Per sfruttare i vantaggi del consenso incrementale, creare un elenco di autorizzazioni (ambiti) usate dall'app dalla registrazione dell'app e organizzarle in due elenchi in base a:

• Ambiti da richiedere durante la prima interazione dell'utente con l'app durante l'accesso.
• Le autorizzazioni associate a una funzionalità importante dell'app che dovrai anche spiegare all'utente.

Dopo aver organizzato gli ambiti, organizzare ogni elenco in base alla risorsa (API) per cui si vuole richiedere un token. Oltre a qualsiasi altro ambito che si desidera far autorizzare all'utente nello stesso momento.

L'oggetto parametri usato per effettuare la richiesta a MSAL supporta:

• Scope: elenco di ambiti per cui si vuole richiedere l'autorizzazione e ricevere un token di accesso.
• ExtraScopesToConsent: elenco aggiuntivo di ambiti per cui si vuole richiedere l'autorizzazione mentre si richiede un token di accesso per un'altra risorsa. Questo elenco di ambiti consente di ridurre al minimo il numero di volte in cui è necessario richiedere l'autorizzazione utente. Ciò significa un minor numero di richieste di autorizzazione o consenso dell'utente.

Eseguire la migrazione da AuthenticationContext a PublicClientApplications

Costruzione di PublicClientApplication

Quando si utilizza MSAL, si crea un'istanza di PublicClientApplication. Questo oggetto modella l'identità dell'app e viene usato per effettuare richieste a una o più autorità. Con questo oggetto si configurerà l'identità client, l'URI di reindirizzamento, l'autorità predefinita, se usare il browser del dispositivo e la visualizzazione Web incorporata, il livello di log e altro ancora.

È possibile configurare in modo dichiarativo questo oggetto con JSON, che viene fornito come file o archiviato come risorsa all'interno del file APK.

Sebbene questo oggetto non sia un singleton, internamente utilizza Executors sia per le richieste interattive sia per quelle silenziose.

Business to Business

In ADAL, ogni organizzazione da cui richiedi token di accesso richiede un'istanza separata di AuthenticationContext. In MSAL questo non è più un requisito. È possibile specificare l'autorità da cui si vuole richiedere un token come parte della richiesta interattiva o invisibile all'utente.

Eseguire la migrazione dalla convalida dell'autorità alle autorità note

MSAL non dispone di un flag per abilitare o disabilitare la verifica dell'autorità. La convalida dell'autorità è una funzionalità di ADAL e nelle versioni iniziali di MSAL, che impedisce al codice di richiedere token da un'autorità potenzialmente dannosa. MSAL recupera ora un elenco di fonti note per Microsoft e unisce l'elenco alle autorità specificate nella configurazione.

Se si tenta di usare un'autorità che non è nota per Microsoft e non è inclusa nella configurazione, si otterrà un oggetto UnknownAuthorityException.

Logging

È ora possibile configurare in modo dichiarativo la registrazione come parte della configurazione, come illustrato di seguito:

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

Eseguire la migrazione da UserInfo all'account

In ADAL, AuthenticationResult fornisce un oggetto UserInfo utilizzato per recuperare informazioni sull'account autenticato. Il termine "utente", che significava un agente umano o software, è stato applicato in modo da rendere difficile comunicare che alcune app supportano un singolo utente (sia un agente umano o software) che ha più account.

Prendere in considerazione un conto bancario. Potresti avere più di un conto presso più di un istituto finanziario. Quando si apre un conto, all’utente vengono fornite credenziali, come una carta BANCOMAT e un PIN, che vengono utilizzate per accedere al saldo, al pagamento delle bollette e così via, per ciascun conto. Tali credenziali possono essere utilizzate solo presso l'istituto finanziario che le ha emesse.

Analogamente, come gli account di un istituto finanziario, gli account nel Microsoft Identity Platform sono accessibili usando le credenziali. Tali credenziali vengono registrate o rilasciate da Microsoft. Oppure da Microsoft per conto di un'organizzazione.

Se il Microsoft Identity Platform differisce da un istituto finanziario, in questa analogia, è che il Microsoft Identity Platform fornisce un framework che consente a un utente di usare un account e le credenziali associate per accedere alle risorse appartenenti a più utenti e organizzazioni. Questo è come essere in grado di utilizzare una carta emessa da una banca, in un altro istituto finanziario. Questo funziona perché tutte le organizzazioni in questione usano il Microsoft Identity Platform, che consente l'uso di un account in più organizzazioni. Ecco un esempio:

Sam funziona per Contoso.com ma gestisce Azure macchine virtuali appartenenti a Fabrikam.com. Per consentire a Sam di gestire le macchine virtuali di Fabrikam, deve essere autorizzato ad accedervi. Questo accesso può essere concesso aggiungendo l'account di Sam a Fabrikam.com e concedendo al suo account un ruolo che gli consente di lavorare con le macchine virtuali. Questa operazione verrà eseguita con il portale di Azure.

L'aggiunta dell'account di Sam in Contoso.com come membro di Fabrikam.com comporterebbe la creazione di un nuovo record nell'ID Microsoft Entra di Fabrikam.com per Sam. Il record di Sam in Microsoft Entra ID è noto come oggetto utente. In questo caso, quell'oggetto utente punterebbe di nuovo all'oggetto utente di Sam in Contoso.com. L'oggetto utente Fabrikam di Sam è la rappresentazione locale di Sam e viene usato per archiviare informazioni sull'account associato a Sam nel contesto di Fabrikam.com. In Contoso.com il titolo di Sam è Senior DevOps Consultant. In Fabrikam il titolo di Sam è Contractor-Macchine virtuali. In Contoso.com Sam non è responsabile, né autorizzato, a gestire le macchine virtuali. In Fabrikam.com, questa è la sua unica funzione di lavoro. Sam ha ancora un solo set di credenziali da tenere traccia, ovvero le credenziali rilasciate da Contoso.com.

Una volta effettuata una chiamata con esito positivo acquireToken , verrà visualizzato un riferimento a un IAccount oggetto che può essere usato nelle richieste successive acquireTokenSilent .

IMultiTenantAccount

Se si dispone di un'app che accede alle attestazioni relative a un account per ciascuno dei tenant in cui l'account è rappresentato, è possibile eseguire il cast degli oggetti IAccount in IMultiTenantAccount. Questa interfaccia fornisce una mappa di ITenantProfiles, indicizzata in base all'ID del tenant, che consente di accedere ai claim appartenenti all'account presente in ciascuno dei tenant da cui hai richiesto un token, relativi all'account corrente.

Le attestazioni nella radice di IAccount e IMultiTenantAccount contengono sempre le attestazioni del tenant principale. Se non è ancora stata effettuata una richiesta di un token nel tenant di origine, questa raccolta sarà vuota.

Altre modifiche

Usa il nuovo 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);
}

Passa alle nuove eccezioni

In ADAL è disponibile un tipo di eccezione, AuthenticationException, che include un metodo per recuperare il valore dell'enumerazione ADALError. In MSAL è presente una gerarchia di eccezioni e ognuno ha un proprio set di codici di errore specifici associati.

Conversione da ADALError a MsalException

Dalla registrazione di ADAL alla registrazione di MSAL

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