Guia de migração da ADAL para MSAL para Android

Este artigo destaca as alterações que você precisa fazer para migrar um aplicativo que usa a Biblioteca de Autenticação Azure Active Directory (ADAL) para usar o Biblioteca do Microsoft Authenticator (MSAL).

Destaques das diferenças

A ADAL funciona com o terminal v1.0 do Azure AD. A Biblioteca do Microsoft Authenticator (MSAL) funciona com a plataforma de identidade da Microsoft, anteriormente conhecida como o endpoint do Azure AD v2.0. O plataforma de identidade da Microsoft é diferente de Azure AD v1.0 no seguinte:

Suporta:

• Identidade organizacional (Microsoft Entra ID)

• Identidades não organizacionais, como Outlook.com, Xbox Live e assim por diante

• (somente Azure AD B2C) Logon federado com Google, Facebook, X e Amazon

• Os padrões são compatíveis com:

  • OAuth v2.0
  • OIDC (OpenID Connect)

A API pública da MSAL apresenta alterações importantes, incluindo:

• Um novo modelo para acessar tokens:
  • O ADAL fornece acesso a tokens por meio de AuthenticationContext, que representa o servidor. A MSAL fornece acesso a tokens por meio do PublicClientApplication, que representa o cliente. Os desenvolvedores cliente não precisam criar uma nova PublicClientApplication instância para cada Autoridade com a qual precisam interagir. Apenas uma PublicClientApplication configuração é necessária.
  • Suporte para solicitar tokens de acesso usando escopos além de identificadores de recursos.
  • Suporte para consentimento incremental. Os desenvolvedores podem solicitar escopos à medida que o usuário acessa cada vez mais funcionalidades no aplicativo, incluindo aquelas não incluídas durante o registro do aplicativo.
  • As autoridades não são mais validadas em tempo de execução. Em vez disso, o desenvolvedor declara uma lista de "autoridades conhecidas" durante o desenvolvimento.
• Alterações na API de token:
  • Na ADAL, AcquireToken() primeiro faz uma solicitação silenciosa. Na falta disso, faz uma requisição interativa. Esse comportamento fez com que alguns desenvolvedores dependessem apenas de AcquireToken, o que fazia com que, às vezes, o usuário fosse solicitado inesperadamente a fornecer credenciais. A MSAL exige que os desenvolvedores sejam intencionais sobre quando o usuário recebe um prompt de interface de usuário.
    • AcquireTokenSilent sempre resulta em uma solicitação silenciosa que pode ser bem-sucedida ou falhar.
    • AcquireToken sempre resulta em uma solicitação ao usuário por meio da interface do usuário.
• O MSAL dá suporte ao logon por um navegador padrão ou por uma exibição da Web incorporada:
  • Por padrão, o navegador padrão no dispositivo é usado. Isso permite que a MSAL use o estado de autenticação (cookies) que já pode estar presente para uma ou mais contas assinadas. Se nenhum estado de autenticação estiver presente, a autenticação durante a autorização via MSAL resultará na criação do estado de autenticação (cookies) em benefício de outros aplicativos Web que serão usados no mesmo navegador.
• Novo modelo de exceção:
  • As exceções definem mais claramente o tipo de erro que ocorreu e o que o desenvolvedor precisa fazer para resolvê-lo.
• A MSAL oferece suporte a objetos de parâmetros para chamadas AcquireToken e AcquireTokenSilent.
• A MSAL dá suporte à configuração declarativa para:
  • ID do cliente, URI de redirecionamento.
  • Navegador Inserido vs Padrão
  • Autoridades
  • Configurações de HTTP, como tempo limite de leitura e conexão

Registro e migração do aplicativo para MSAL

Você não precisa alterar o registro de aplicativo existente para usar a MSAL. Se você quiser aproveitar o consentimento incremental/progressivo, talvez seja necessário examinar o registro para identificar os escopos específicos que deseja solicitar incrementalmente. A seguir, mais informações sobre escopos e consentimento incremental.

No registro do aplicativo no portal, você verá uma guia de permissões de API . Isso fornece uma lista das APIs e permissões (escopos) às quais seu aplicativo está configurado no momento para solicitar acesso. Ele também mostra uma lista dos nomes de escopo associados a cada permissão de API.

Consentimento do usuário

Com o ADAL e o endpoint do Azure AD v1.0, o consentimento do usuário para recursos de sua propriedade era concedido no primeiro uso. Com a MSAL e a plataforma de identidade da Microsoft, o consentimento pode ser solicitado incrementalmente. O consentimento incremental é útil para permissões que um usuário pode considerar de alto privilégio ou pode questionar se não for fornecido uma explicação clara de por que a permissão é necessária. No ADAL, essas permissões podem ter levado o usuário a desistir de entrar no seu aplicativo.

Autorização de administrador

Os administradores da organização podem consentir com permissões que seu aplicativo requer em nome de todos os membros de sua organização. Algumas organizações permitem que somente os administradores concedam consentimento a aplicativos. O consentimento do administrador requer que você inclua todas as permissões de API e escopos usados pelo aplicativo no registro do aplicativo.

Migrando de IDs de recursos para escopos

Autenticar e solicitar autorização para todas as permissões no primeiro uso

Se você estiver usando a ADAL e não precisar usar o consentimento incremental, a maneira mais simples de começar a usar a MSAL é fazer uma solicitação acquireToken usando o novo AcquireTokenParameter objeto e definir o valor da ID do recurso.

Isso resultará no mesmo comportamento da v1 ao qual você está acostumado. Todas as permissões solicitadas no registro do aplicativo são solicitadas ao usuário durante a primeira interação.

Autenticar e solicitar permissões somente conforme necessário

Para aproveitar o consentimento incremental, faça uma lista de permissões (escopos) que seu aplicativo usa do registro do aplicativo e organize-as em duas listas com base em:

• Quais escopos você deseja solicitar na primeira interação do usuário com seu aplicativo durante o login.
• As permissões associadas a um recurso importante do seu aplicativo que você também precisará explicar ao usuário.

Depois de organizar os escopos, organize cada lista para qual recurso (API) você deseja solicitar um token. Bem como quaisquer outros escopos que você deseja que o usuário autorize ao mesmo tempo.

O objeto de parâmetros usado para fazer sua solicitação para MSAL dá suporte a:

• Scope: a lista de escopos para os quais você deseja solicitar autorização e receber um token de acesso.
• ExtraScopesToConsent: uma lista adicional de escopos para os quais você deseja solicitar autorização enquanto solicita um token de acesso para outro recurso. Essa lista de escopos permite minimizar o número de vezes que você precisa para solicitar a autorização do usuário. O que significa menos solicitações de autorização ou consentimento do usuário.

Migrar de AuthenticationContext para PublicClientApplications

Criando PublicClientApplication

Quando você usa a MSAL, instancia um PublicClientApplication. Esse objeto modela sua identidade de aplicativo e é usado para fazer solicitações a uma ou mais autoridades. Com esse objeto, você configurará a identidade do cliente, o URI de redirecionamento, a autoridade padrão, se deseja usar o navegador do dispositivo versus o modo de exibição da Web inserido, o nível de log e muito mais.

Você pode configurar declarativamente esse objeto com JSON, que você fornece como um arquivo ou armazena como um recurso em seu APK.

Embora esse objeto não seja um singleton, internamente ele usa Executors compartilhado para solicitações interativas e silenciosas.

Empresa para Empresa

Na ADAL, todas as organizações das quais você solicita tokens de acesso exigem uma instância separada da AuthenticationContext. Na MSAL, isso não é mais um requisito. Você pode especificar a autoridade da qual deseja solicitar um token como parte de sua solicitação silenciosa ou interativa.

Migrar da validação de autoridade para autoridades conhecidas

A MSAL não tem um sinalizador para habilitar ou desabilitar a validação da autoridade. A validação de autoridade é um recurso na ADAL e, nas primeiras versões da MSAL, que impede que seu código solicite tokens de uma autoridade potencialmente mal-intencionada. O MSAL agora obtém uma lista de autoridades conhecidas pela Microsoft e mescla essa lista com as autoridades que você especificou na sua configuração.

Se você tentar usar uma autoridade que não é conhecida por Microsoft e não está incluída em sua configuração, você receberá uma UnknownAuthorityException.

Logging

Agora você pode configurar declarativamente o registro em log como parte de sua configuração, desta forma:

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

Migrar de UserInfo para Conta

Na ADAL, o AuthenticationResult fornece um UserInfo objeto usado para recuperar informações sobre a conta autenticada. O termo "usuário", que significava um agente humano ou de software, foi aplicado de uma forma que dificultava a comunicação de que alguns aplicativos dão suporte a um único usuário (seja um agente humano ou de software) que tenha várias contas.

Considere uma conta bancária. Você pode ter mais de uma conta em mais de uma instituição financeira. Quando você abre uma conta, você (o usuário) recebe credenciais, como um CARTÃO DE CAIXA ELETRÔNICO &PIN, que são usadas para acessar seu saldo, pagamentos de cobrança e assim por diante, para cada conta. Essas credenciais só podem ser usadas na instituição financeira que as emitiu.

Por analogia, como contas em uma instituição financeira, as contas no plataforma de identidade da Microsoft são acessadas usando credenciais. Essas credenciais são registradas ou emitidas por Microsoft. Ou pela Microsoft em nome de uma organização.

Quando o plataforma de identidade da Microsoft difere de uma instituição financeira, nessa analogia, é que o plataforma de identidade da Microsoft fornece uma estrutura que permite que um usuário use uma conta e suas credenciais associadas para acessar recursos que pertencem a vários indivíduos e organizações. Isso é como poder usar um cartão emitido por um banco, em outra instituição financeira. Isso funciona porque todas as organizações em questão estão usando o plataforma de identidade da Microsoft, que permite que uma conta seja usada em várias organizações. Veja um exemplo:

Sam trabalha para Contoso.com mas gerencia Azure máquinas virtuais que pertencem a Fabrikam.com. Para Sam gerenciar as máquinas virtuais da Fabrikam, ele precisa estar autorizado a acessá-las. Esse acesso pode ser concedido adicionando a conta de Sam a Fabrikam.com e concedendo a sua conta uma função que lhe permita trabalhar com as máquinas virtuais. Isso seria feito com o portal Azure.

Adicionar a conta Contoso.com de Sam como membro do Fabrikam.com resultaria na criação de um novo registro no Microsoft Entra ID do Fabrikam.com para Sam. O registro de Sam em Microsoft Entra ID é conhecido como um objeto de usuário. Nesse caso, esse objeto de usuário apontaria de volta para o objeto de usuário do Sam em Contoso.com. O objeto de usuário fabrikam de Sam é a representação local de Sam e seria usado para armazenar informações sobre a conta associada ao Sam no contexto de Fabrikam.com. Em Contoso.com, o título de Sam é Consultor Sênior de DevOps. Em Fabrikam, o título de Sam é Contractor-Máquinas Virtuais. Em Contoso.com, Sam não é responsável nem autorizado a gerenciar máquinas virtuais. Em Fabrikam.com, essa é sua única função de trabalho. No entanto, Sam ainda tem apenas um conjunto de credenciais para acompanhar, que são as credenciais emitidas por Contoso.com.

Depois que uma chamada bem-sucedida acquireToken for feita, você verá uma referência a um IAccount objeto que pode ser usado em solicitações posteriores acquireTokenSilent .

IMultiTenantAccount

Se você tiver um aplicativo que acesse declarações sobre uma conta de cada locatário no qual a conta é representada, você pode converter objetos IAccount em IMultiTenantAccount. Essa interface fornece um mapa de ITenantProfiles, inserido pela ID do locatário, que permite que você acesse as declarações que pertencem à conta em cada um dos locatários dos quais você solicitou um token, em relação à conta atual.

As declarações na raiz de IAccount e IMultiTenantAccount sempre contêm as declarações do locatário da página inicial. Se você ainda não fez uma solicitação para um token no locatário da página inicial, essa coleção estará vazia.

Outras alterações

Usar o novo 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);
}

Migrar para as novas exceções

Na ADAL, há um tipo de exceção, AuthenticationException, que inclui um método para recuperar o valor da enumeração ADALError. Na MSAL, há uma hierarquia de exceções e cada uma tem seu próprio conjunto de códigos de erro específicos associados.

Tradução de ADALError para MsalException

Registro na ADAL no Registro na 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
}