Migrar aplicativos iOS que usam o Microsoft Authenticator de ADAL.NET para MSAL.NET

  • Artigo

Você tem usado a Biblioteca de Autenticação do Azure Active Directory para .NET (ADAL.NET) e o agente do iOS. Agora é hora de migrar para a Biblioteca de Autenticação da Microsoft para .NET (MSAL.NET), que dá suporte ao agente no iOS versão 4.3 em diante.

Por onde você deve começar? Este artigo ajuda você a migrar seu aplicativo Xamarin iOS de ADAL para MSAL.

Pré-requisitos

Este artigo pressupõe que você já tenha um aplicativo Xamarin iOS integrado ao agente do iOS. Caso contrário, migre diretamente para MSAL.NET e comece a implementação do agente. Para obter informações sobre como invocar o agente do iOS em MSAL.NET com um novo aplicativo, confira esta documentação.

Segundo plano

O que são agentes?

Os agentes são aplicativos fornecidos pela Microsoft no Android e no iOS. (Confira o aplicativo Microsoft Authenticator no iOS e Android e o aplicativo Portal da Empresa do Intune no Android.)

Eles permitem:

Migrar de ADAL para MSAL

Etapa 1: habilitar o agente

Código de ADAL atual:Equivalente de MSAL:
Na ADAL.NET, o suporte ao agente foi habilitado com base no contexto por autenticação. Isso está desabilitado por padrão. Você precisava definir um

sinalizador useBroker como true no construtor PlatformParameters para chamar o agente:

public PlatformParameters(
        UIViewController callerViewController,
        bool useBroker)

Além disso, no código específico da plataforma, neste exemplo, no renderizador de página para iOS, defina o sinalizador sinalizador useBroker como verdadeiro:

page.BrokerParameters = new PlatformParameters(
          this,
          true,
          PromptBehavior.SelectAccount);

Em seguida, inclua os parâmetros na chamada de token de aquisição:

 AuthenticationResult result =
                    await
                        AuthContext.AcquireTokenAsync(
                              Resource,
                              ClientId,
                              new Uri(RedirectURI),
                              platformParameters)
                              .ConfigureAwait(false);
Na MSAL.NET, o suporte do Broker é habilitado por PublicClientApplication. Isso está desabilitado por padrão. Para habilitá-lo, use o parâmetro

WithBroker() (definido como true por padrão) para chamar o agente:

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos)
                .Build();

Na chamada de aquisição de token:

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

Etapa 2: definir um UIViewController()

Na ADAL.NET, você passou um UIViewController como parte do PlatformParameters. (Confira o exemplo na Etapa 1.) Na MSAL.NET, para fornecer maior flexibilidade aos desenvolvedores, uma janela de objeto é usada, mas não é necessária no uso regular do iOS. Para usar o agente, defina a janela de objeto para enviar e receber respostas do agente.

Código de ADAL atual:Equivalente de MSAL:
Um UIViewController é passado para

PlatformParameters na plataforma específica do iOS.

page.BrokerParameters = new PlatformParameters(
          this,
          true,
          PromptBehavior.SelectAccount);
Na MSAL.NET, faça duas ações para definir a janela de objeto para o iOS:
  1. No AppDelegate.cs, defina o App.RootViewController para um novo UIViewController(). Essa atribuição garante que haja um UIViewController com a chamada para o agente. Se não estiver definido corretamente, você poderá receber esse erro: "uiviewcontroller_required_for_ios_broker":"UIViewController is null, so MSAL.NET cannot invoke the iOS broker. See https://aka.ms/msal-net-ios-broker"
  2. Na chamada AcquireTokenInteractive, use .WithParentActivityOrWindow(App.RootViewController) e passe a referência à janela de objeto que você usará.

Por exemplo:

Em App.cs:

   public static object RootViewController { get; set; }

Em AppDelegate.cs:

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

Na chamada de aquisição de token:

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

Etapa 3: atualizar o AppDelegate para manipular o retorno de chamada

A ADAL e a MSAL chamam o agente que, por sua vez, chama o seu aplicativo por meio do método OpenUrl da classe AppDelegate. Para obter mais informações, veja esta documentação.

Não há nenhuma alteração aqui entre ADAL.NET e MSAL.NET.

Etapa 4: registrar um esquema de URL

ADAL.NET e MSAL.NET usam URLs para invocar o agente e retornar a resposta do agente de volta para o aplicativo. Registre o esquema de URL no arquivo Info.plist para seu aplicativo da seguinte forma:

Código de ADAL atual:Equivalente de MSAL:
O esquema de URL é exclusivo para seu aplicativo. O

O nome CFBundleURLSchemes deve incluir

msauth.

como um prefixo, seguido pelo seu CFBundleURLName

Por exemplo: $"msauth.(BundleId")

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

Observação

Esse esquema de URL se torna parte do URI de redirecionamento usado para identificar exclusivamente o aplicativo quando ele recebe a resposta do agente.

Etapa 5: adicionar o identificador do agente à seção LSApplicationQueriesSchemes

A ADAL.NET e a MSAL.NET usam -canOpenURL: para verificar se o agente está instalado no dispositivo. Adicione o identificador correto para o agente do iOS à seção LSApplicationQueriesSchemes do arquivo info.plist da seguinte maneira:

Código de ADAL atual:Equivalente de MSAL:
Usos

msauth

<key>LSApplicationQueriesSchemes</key>
<array>
     <string>msauth</string>
</array>
Usos

msauthv2

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

Etapa 6: registrar o URI de redirecionamento no portal do Azure

ADAL.NET e MSAL.NET adicionam um requisito extra ao URI de redirecionamento ao direcionar o agente. Registre o URI de redirecionamento com seu aplicativo no portal do Azure.

Código de ADAL atual:Equivalente de MSAL:

"<app-scheme>://<your.bundle.id>"

Exemplo:

mytestiosapp://com.mycompany.myapp

$"msauth.{BundleId}://auth"

Exemplo:

public static string redirectUriOnIos = "msauth.com.yourcompany.XForms://auth";

Para obter mais informações sobre como registrar o URI de redirecionamento no portal do Azure, confira Etapa 7: adicionar um URI de redirecionamento ao registro do aplicativo.

Etapa 7: Definir o Entitlements.plist

Habilite o acesso ao conjunto de chaves no arquivo Entitlements.plist:

 <key>keychain-access-groups</key>
    <array>
      <string>$(AppIdentifierPrefix)com.microsoft.adalcache</string>
    </array>

Para obter mais informações sobre como habilitar o acesso ao conjunto de chaves, confira Habilitar o acesso ao conjunto de chaves.

Próximas etapas

Saiba mais sobre Considerações específicas de iOS do Xamarin com a MSAL.NET.