Usar o Microsoft Authenticator ou o Portal da Empresa do Intune em aplicativos Xamarin

Para Android e iOS, os agentes como o Microsoft Authenticator e o Portal da Empresa do Microsoft Intune (específico do Android) habilitam:

• Logon único (SSO) : os usuários não precisam entrar em cada aplicativo.
• Identificação do dispositivo: o agente acessa o certificado do dispositivo. Esse certificado é criado no dispositivo ao associá-lo ao local de trabalho.
• Verificação da identificação do aplicativo: quando um aplicativo chama o agente, ele transmite sua URL de redirecionamento. O agente a verifica a URL.

Para habilitar um desses recursos, use o parâmetro WithBroker() ao chamar o método PublicClientApplicationBuilder.CreateApplication. Por padrão, o parâmetro .WithBroker() é definido como true.

A configuração da autenticação agenciada na biblioteca de autenticação da Microsoft para .NET (MSAL.NET) varia de acordo com a plataforma:

• Aplicativos iOS
• Aplicativos Android

Autenticação agenciada para iOS

Use as etapas a seguir para habilitar a comunicação entre seu aplicativo Xamarin.iOS e o aplicativo Microsoft Authenticator. Para o iOS 13, considere a leitura de Alteração interruptiva da API da Apple.

Etapa 1: habilitar o suporte ao agente

Você deve habilitar o suporte do agente para instâncias individuais do PublicClientApplication. O suporte é desabilitado por padrão. Ao criar PublicClientApplication por meio de PublicClientApplicationBuilder, use o parâmetro WithBroker() como mostra o exemplo a seguir. Por padrão, o parâmetro WithBroker() é definido como true.

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithReplyUri(redirectUriOnIos) // $"msauth.{Bundle.Id}://auth" (see step 6 below)
                .Build();

Etapa 2: habilitar o acesso ao conjunto de chaves

Para habilitar o acesso ao conjunto de chaves, obtenha um grupo de acesso de conjunto de chaves para seu aplicativo. Use a API WithIosKeychainSecurityGroup() para definir o grupo de acesso do conjunto de chaves ao criar seu aplicativo:

var builder = PublicClientApplicationBuilder
     .Create(ClientId)
     .WithIosKeychainSecurityGroup("com.microsoft.adalcache")
     .Build();

Para obter mais informações, consulte Habilitar o acesso ao conjunto de chaves.

Etapa 3: atualizar o AppDelegate para lidar com o retorno de chamada

Quando o MSAL.NET chama o agente, ele retorna a chamada ao seu aplicativo por meio do método OpenUrl da classe AppDelegate. Como o MSAL aguarda a resposta do agente, seu aplicativo precisa cooperar chamando MSAL.NET de volta. A fim de permitir essa cooperação, atualize o arquivo AppDelegate.cs para substituir o método a seguir.

public override bool OpenUrl(UIApplication app, NSUrl url,
                             string sourceApplication,
                             NSObject annotation)
{
    if (AuthenticationContinuationHelper.IsBrokerResponse(sourceApplication))
    {
      AuthenticationContinuationHelper.SetBrokerContinuationEventArgs(url);
      return true;
    }

    else if (!AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(url))
    {
         return false;
    }

    return true;
}

Esse método é invocado toda vez que o aplicativo é iniciado. Ele representa uma oportunidade de processar a resposta do agente e concluir o processo de autenticação iniciado pelo MSAL.NET.

Etapa 4: configurar UIViewController()

Ainda no arquivo AppDelegate.cs, configure uma janela de objeto. Normalmente, você não precisa definir a janela de objeto para o Xamarin iOS, mas precisa de uma janela de objeto para enviar e receber respostas do agente.

Para configurar a janela de objeto:

1. No arquivo AppDelegate.cs, configure App.RootViewController como um novo UIViewController(). Essa atribuição garante que a chamada ao agente inclua UIViewController. Se a configuração for atribuída incorretamente, você poderá receber este 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 transmita a referência à janela de objeto que será usada.

   No App.cs:

      public static object RootViewController { get; set; }
   

   No AppDelegate.cs:

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

   Na chamada AcquireToken:

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

Etapa 5: registrar um esquema de URL

O MSAL.NET usa URLs para invocar o agente e retornar a resposta dele ao seu aplicativo. Para concluir a viagem de ida e volta, registre um esquema de URL para o seu aplicativo no arquivo Info.plist.

O nome CFBundleURLSchemes deve incluir msauth. como um prefixo. Após o prefixo, acrescente CFBundleURLName.

No esquema de URL, BundleId identifica exclusivamente o aplicativo: $"msauth.(BundleId)". Portanto, se BundleId for com.yourcompany.xforms, o esquema de URL será msauth.com.yourcompany.xforms.

Observação

Esse esquema de URL se tornará parte do URI de redirecionamento que identifica exclusivamente seu aplicativo quando ele recebe a resposta do agente.

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

Etapa 6: adicionar o identificador de agente à seção LSApplicationQueriesSchemes

O MSAL usa –canOpenURL: para verificar se o agente está instalado no dispositivo. No iOS 9, a Apple bloqueou os esquemas que um aplicativo pode consultar.

Adicione msauthv2 à seção LSApplicationQueriesSchemes do arquivo Info.plist, conforme o exemplo a seguir:

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

Etapa 7: adicionar um URI de redirecionamento ao registro do aplicativo

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

O URI de redirecionamento tem um requisito adicional ao usar o agente. O URI de redirecionamento deve ter o seguinte formato:

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

Veja um exemplo:

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

Observe que o URI de redirecionamento corresponde ao nome CFBundleURLSchemes incluído no arquivo Info.plist.

Adicione o URI de redirecionamento ao registro do aplicativo. Para gerar um URI de redirecionamento formatado corretamente, use os Registros de aplicativo para gerar o URI de redirecionamento intermediado pela ID do pacote.

Para gerar o URI de redirecionamento:

1. Entre no Centro de administração do Microsoft Entra com pelo menos a função de Administrador de Aplicativo de nuvem.

2. Navegue até Identidade>Aplicativos>Registros do aplicativo.

3. Pesquise e selecione o aplicativo.

4. Selecione Autenticação>Adicionar uma plataforma>iOS/macOS

5. Insira o ID do pacote e, em seguida, selecione Configurar.

   Copie o URI de redirecionamento gerado que aparece na caixa de texto URI de redirecionamento para incluir no código:

   

6. Selecione Concluído para concluir a geração do URI de redirecionamento.

Autenticação agenciada para Android

Etapa 1: habilitar o suporte ao agente

O suporte ao agente é habilitado por PublicClientApplication. Isso está desabilitado por padrão. Use o parâmetro WithBroker() (definido como true por padrão) ao criar IPublicClientApplication por meio de PublicClientApplicationBuilder.

var app = PublicClientApplicationBuilder
                .Create(ClientId)
                .WithBroker()
                .WithRedirectUri(redirectUriOnAndroid) // See step #4
                .Build();

Etapa 2: Atualizar a atividade principal para lidar com o retorno de chamada

Quando o MSAL.NET chama o agente, ele retorna a chamada ao seu aplicativo com o método OnActivityResult(). Como o MSAL aguarda a resposta do agente, seu aplicativo precisa rotear o resultado para o MSAL.NET.

Encaminhe o resultado para o método SetAuthenticationContinuationEventArgs(int requestCode, Result resultCode, Intent data) substituindo o método OnActivityResult(), como a seguir:

protected override void OnActivityResult(int requestCode, Result resultCode, Intent data)
{
   base.OnActivityResult(requestCode, resultCode, data);
   AuthenticationContinuationHelper.SetAuthenticationContinuationEventArgs(requestCode, resultCode, data);
}

Esse método é invocado toda vez que o aplicativo agente é iniciado e representa uma oportunidade de processar a resposta do agente e concluir o processo de autenticação iniciado pelo MSAL.NET.

Etapa 3: definir uma atividade

Para habilitar a autenticação agenciada, defina uma atividade para que o MSAL possa enviar e receber a resposta do agente. Para isso, forneça a atividade (geralmente, MainActivity) ao objeto pai WithParentActivityOrWindow(object parent).

Por exemplo, na chamada para AcquireTokenInteractive():

result = await app.AcquireTokenInteractive(scopes)
             .WithParentActivityOrWindow((Activity)context))
             .ExecuteAsync();

Etapa 4: adicionar um URI de redirecionamento ao registro do aplicativo

O MSAL usa URLs para invocar o agente e retornar a resposta ao aplicativo. Para concluir essa viagem de ida e volta, registre um URI de Redirecionamento no seu aplicativo.

O formato do URI de redirecionamento para seu aplicativo depende do certificado usado para assinar o APK. Por exemplo:

msauth://com.microsoft.xforms.testApp/hgbUYHVBYUTvuvT&Y6tr554365466=

A última parte do URI, hgbUYHVBYUTvuvT&Y6tr554365466=, é a versão codificada em Base64 da assinatura do APK. Ao desenvolver seu aplicativo no Visual Studio e depurar seu código sem assinar o APK com um certificado específico, o Visual Studio assina o APK por você para fins de depuração. Quando o Visual Studio assina o APK, ele fornece uma assinatura exclusiva para o computador no qual foi criado. Po isso, sempre que você criar seu aplicativo em um computador diferente, precisará atualizar o URI de redirecionamento no código do aplicativo e o registro do aplicativo para a autenticação no MSAL.

Durante a depuração, é possível encontrar uma exceção MSAL (ou mensagem de log) informando que o URI de redirecionamento fornecido está incorreto. A exceção ou a mensagem de log também indica o URI de redirecionamento que você deve usar com o computador atual em que você está depurando. Você pode usar o URI de redirecionamento fornecido para continuar desenvolvendo seu aplicativo, desde que atualize o URI de redirecionamento no código e adicione o URI de redirecionamento fornecido ao registro do aplicativo.

Quando você estiver pronto para finalizar seu código, atualize o URI de redirecionamento no código e o registro do aplicativo para usar a assinatura do certificado que você usou para assinar o APK.

Na prática, isso significa que é recomendado adicionar um URI de redirecionamento para cada membro da equipe de desenvolvimento, além de um URI de redirecionamento para a versão assinada de produção do APK.

Você pode calcular a assinatura por conta própria, de forma semelhante ao MSAL:

   private string GetRedirectUriForBroker()
   {
      string packageName = Application.Context.PackageName;
      string signatureDigest = this.GetCurrentSignatureForPackage(packageName);
      if (!string.IsNullOrEmpty(signatureDigest))
      {
            return string.Format(CultureInfo.InvariantCulture, "{0}://{1}/{2}", RedirectUriScheme,
               packageName.ToLowerInvariant(), signatureDigest);
      }

      return string.Empty;
   }

   private string GetCurrentSignatureForPackage(string packageName)
   {
      Android.Content.PM.Signature signature = null;
      if (Build.VERSION.SdkInt >= BuildVersionCodes.Tiramisu)
      {
          var packageInfo = Application.Context.PackageManager.GetPackageInfo(packageName, PackageManager.PackageInfoFlags.Of((long)PackageInfoFlags.SigningCertificates));
          if (packageInfo.SigningInfo != null)
          {
              var signatures = packageInfo.SigningInfo.GetApkContentsSigners();
              if (signatures != null && signatures.Length > 0)
                  signature = signatures[0];
          }
      }
      else
      {
#pragma warning disable CS0618 // Type or member is obsolete
          var packageInfo = Application.Context.PackageManager.GetPackageInfo(packageName, PackageInfoFlags.Signatures);
          if (packageInfo != null && packageInfo.Signatures != null && packageInfo.Signatures.Count > 0)
              signature = packageInfo.Signatures[0];
#pragma warning restore CS0618 // Type or member is obsolete
      }
    
      if (signature != null)
      {
          // First available signature. Applications can be signed with multiple signatures.
          // The order of Signatures is not guaranteed.
          var md = MessageDigest.GetInstance("SHA");
          md.Update(signature.ToByteArray());
          return Convert.ToBase64String(md.Digest(), Base64FormattingOptions.None);
          // Server side needs to register all other tags. ADAL will
          // send one of them.
      }
   }

Você também tem a opção de adquirir a assinatura do pacote usando keytool com os seguintes comandos:

• Windows:

  keytool.exe -list -v -keystore "%LocalAppData%\Xamarin\Mono for Android\debug.keystore" -alias androiddebugkey -storepass android -keypass android
  

• macOS:

  keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64
  

Etapa 5 (opcional): fazer fallback para o navegador do sistema

Se o MSAL estiver configurado para usar o agente, mas o agente não estiver instalado, o MSAL fará fallback e usará uma visualização da Web (um navegador). Ele tentará realizar a autenticação com o navegador do sistema padrão no dispositivo, que falhará, pois o URI de redirecionamento está configurado para o agente e o navegador do sistema não sabe como usá-lo para navegar de volta para o MSAL. Para evitar a falha, configure um filtro de intenção com o URI de redirecionamento do agente usado na etapa 4.

Modifique o manifesto do aplicativo para adicionar o filtro de intenção:

<!-- NOTE the SLASH (required) that prefixes the signature value in the path attribute.
     The signature value is the Base64-encoded signature discussed above. -->
<intent-filter>
      <data android:scheme="msauth"
                    android:host="Package Name"
                    android:path="/Package Signature"/>

Por exemplo, se você tiver um URI de redirecionamento msauth://com.microsoft.xforms.testApp/hgbUYHVBYUTvuvT&Y6tr554365466=, seu manifesto deverá ser parecido com o snippet XML a seguir.

A barra (/) na frente da assinatura no valor android:path é necessária.

<!-- NOTE the SLASH (required) that prefixes the signature value in the path attribute.
     The signature value is the Base64-encoded signature discussed above. -->
<intent-filter>
      <data android:scheme="msauth"
                    android:host="com.microsoft.xforms.testApp"
                    android:path="/hgbUYHVBYUTvuvT&Y6tr554365466="/>

Para obter mais informações sobre como configurar seu aplicativo para o suporte do navegador do sistema e do Android 11, consulte Atualizar o manifesto do Android para o suporte ao navegador do sistema.

Como alternativa, você pode configurar o MSAL para fazer fallback para o navegador incorporado, que não depende de um URI de redirecionamento:

.WithUseEmbeddedWebUi(true)

Dicas de solução de problemas para autenticação agenciada do Android

Veja a seguir algumas dicas sobre como evitar problemas ao implementar a autenticação agenciada no Android:

• URI de redirecionamento: adicione um URI de redirecionamento ao registro do seu aplicativo. Um URI de redirecionamento ausente ou incorreto é um problema comum encontrado pelos desenvolvedores.

• Versão do agente – instale a versão mínima necessária dos aplicativos do agente. Qualquer um desses dois aplicativos pode ser usado para a autenticação agenciada no Android.

  • Portal da Empresa do Intune (versão 5.0.4689.0 ou mais recente)
  • Microsoft Authenticator (versão 6.2001.0140 ou mais recente).

• Precedência do agente - o MSAL se comunica com o primeiro agente instalado no dispositivo quando vários estão presentes.

  Exemplo: ao instalar primeiro o Microsoft Authenticator e, em seguida, o Portal da Empresa do Intune, a autenticação agenciada ocorrerá apenas no Microsoft Authenticator.

• Logs – ao encontrar um problema com a autenticação agenciada, veja os logs do agente, que podem ser úteis no diagnóstico da causa.

  • Obter os logs do Microsoft Authenticator:

    1. Selecione o botão de menu no canto superior direito do aplicativo.
    2. Selecione Enviar comentários>Você está com problemas? .
    3. Em O que você está tentando fazer? , selecione uma opção e adicione uma descrição.
    4. Para enviar os logs, selecione a seta no canto superior direito do aplicativo.

    Depois de enviar os logs, uma caixa de diálogo exibirá o ID do incidente. Registre o ID do incidente para incluí-lo ao solicitar assistência.

  • Obtenha os logs do Portal da Empresa do Intune:

    1. Selecione o botão de menu no canto superior esquerdo do aplicativo.
    2. Selecione Ajuda>Suporte por email.
    3. Para enviar os logs, selecione Carregar apenas logs.

    Depois de enviar os logs, uma caixa de diálogo exibirá o ID do incidente. Registre o ID do incidente para incluí-lo ao solicitar assistência.

Próximas etapas

Saiba mais sobre Considerações ao usar a Plataforma Universal do Windows com MSAL.NET.