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

No Android e iOS, corretores como o Microsoft Authenticator e o Portal da Empresa do Microsoft Intune específico para Android permitem:

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

Para habilitar um desses recursos, use o parâmetro quando você chamar o WithBroker()PublicClientApplicationBuilder.CreateApplication método. O .WithBroker() parâmetro é definido como true por padrão.

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

• Aplicações iOS
• Aplicações Android

Autenticação intermediada para iOS

Use as etapas a seguir para permitir que seu aplicativo Xamarin.iOS se comunique com o aplicativo Microsoft Authenticator . Se você estiver visando o iOS 13, considere ler sobre a mudança de API da Apple.

Etapa 1: Habilitar o suporte ao broker

Você deve habilitar o suporte ao broker para instâncias individuais do PublicClientApplication. O suporte está desativado por padrão. Ao criar PublicClientApplication através PublicClientApplicationBuilderdo , use o parâmetro como mostra o WithBroker() exemplo a seguir. O WithBroker() parâmetro é definido como true por padrão.

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

Etapa 2: Habilitar o acesso às chaves

Para habilitar o acesso às chaves, você deve ter um grupo de acesso às chaves para seu aplicativo. Você pode usar a WithIosKeychainSecurityGroup() API para definir seu grupo de acesso às chaves ao criar seu aplicativo:

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

Para obter mais informações, consulte Habilitar acesso às chaves.

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

Quando MSAL.NET chama o broker, o broker chama de volta para seu aplicativo através do OpenUrl método da AppDelegate classe. Como a MSAL aguarda a resposta do corretor, seu aplicativo precisa cooperar para chamar MSAL.NET de volta. Para habilitar 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 é usado como uma oportunidade para processar a resposta do corretor e concluir o processo de autenticação que MSAL.NET iniciado.

Etapa 4: Definir UIViewController()

Ainda no arquivo AppDelegate.cs, defina 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 broker.

Para configurar a janela de objeto:

1. No arquivo AppDelegate.cs , defina App.RootViewController como um novo UIViewController()arquivo . Essa atribuição garante que a chamada para o corretor inclua UIViewController. Se essa 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. AcquireTokenInteractive Na chamada, use .WithParentActivityOrWindow(App.RootViewController) e passe a referência para a janela de objeto que você usará.

   No App.cs:

      public static object RootViewController { get; set; }
   

   No AppDelegate.cs:

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

   AcquireToken No convite:

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

Etapa 5: Registrar um esquema de URL

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

O CFBundleURLSchemes nome deve incluir msauth. como um prefixo. Siga o prefixo com CFBundleURLName.

No esquema de URL, BundleId identifica exclusivamente o aplicativo: $"msauth.(BundleId)". Então, se BundleId é , então o esquema de URL é com.yourcompany.xformsmsauth.com.yourcompany.xforms.

Nota

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

 <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 do broker à seção LSApplicationQueriesSchemes

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

Adicione msauthv2 à LSApplicationQueriesSchemes seção do arquivo Info.plist , como no 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

Gorjeta

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

Quando você usa o corretor, seu URI de redirecionamento tem um requisito extra. O URI de redirecionamento deve ter o seguinte formato:

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

Eis um exemplo:

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

Observe que o URI de redirecionamento corresponde ao CFBundleURLSchemes nome que você incluiu no arquivo Info.plist .

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

Para gerar o URI de redirecionamento:

1. Entre no centro de administração do Microsoft Entra como pelo menos um administrador de aplicativos na nuvem.

2. Navegue até Registros do aplicativo Identity>Applications>.

3. Procure e selecione o aplicativo.

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

5. Introduza 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 inclusão no código:

   

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

Autenticação intermediada para Android

Etapa 1: Habilitar o suporte ao broker

O suporte ao corretor é ativado porPublicClientApplication opção. Está desativada por predefinição. Use o parâmetro (definido como true por padrão) ao criar o WithBroker()IPublicClientApplication através do 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 MSAL.NET chama o corretor, o corretor, por sua vez, ligará de volta para o seu aplicativo com o OnActivityResult() método. Como a MSAL aguardará a resposta do corretor, seu aplicativo precisa rotear o resultado para MSAL.NET.

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

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 do broker é iniciado e é usado como uma oportunidade para processar a resposta do broker e concluir o processo de autenticação iniciado pelo MSAL.NET.

Etapa 3: Definir uma atividade

Para habilitar a autenticação intermediada, defina uma atividade para que a MSAL possa enviar e receber a resposta de e para o broker. Para fazer isso, forneça a atividade (geralmente o ) para WithParentActivityOrWindow(object parent) o MainActivityobjeto pai.

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, em seguida, retornar ao seu aplicativo. Para concluir essa viagem de ida e volta, registre um URI de redirecionamento para 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 com a qual o APK está assinado. Ao desenvolver seu aplicativo no Visual Studio, se você estiver depurando seu código sem assinar o APK com um certificado específico, o Visual Studio assinará o APK para você para fins de depuração. Quando o Visual Studio assina o APK para você dessa forma, ele dá a ele uma assinatura exclusiva para a máquina na qual ele foi criado. Assim, cada vez que você criar seu aplicativo em uma máquina diferente, precisará atualizar o URI de redirecionamento no código do aplicativo e no registro do aplicativo para autenticar com o MSAL.

Durante a depuração, você pode encontrar uma exceção MSAL (ou mensagem de log) informando que o URI de redirecionamento fornecido está incorreto. A exceção ou mensagem de log também indica o URI de redirecionamento que você deve usar com a máquina atual na qual 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 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 com o qual você assina o APK.

Na prática, isso significa que você deve considerar a adição de um URI de redirecionamento para cada membro da sua equipe de desenvolvimento, além de um URI de redirecionamento para a versão assinada de produção do APK.

Você mesmo pode calcular a assinatura, semelhante a como a MSAL faz isso:

   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 para o seu 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
  

Passo 5 (opcional): Volte para o navegador do sistema

Se a MSAL estiver configurada para usar o broker, mas o broker não estiver instalado, o MSAL voltará a usar uma exibição da Web (um navegador). O MSAL tentará autenticar usando o navegador do sistema padrão no dispositivo, o que falha porque o URI de redirecionamento está configurado para o broker e o navegador do sistema não sabe como usá-lo para navegar de volta ao MSAL. Para evitar a falha, você pode configurar um filtro de intenção com o URI de redirecionamento do broker 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 do , seu manifesto deverá se parecer com o seguinte trecho XML msauth://com.microsoft.xforms.testApp/hgbUYHVBYUTvuvT&Y6tr554365466=.

A barra (/) na frente da assinatura no android:path valor é 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 navegador do sistema e suporte ao Android 11, consulte Atualizar o manifesto do Android para suporte ao navegador do sistema.

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

.WithUseEmbeddedWebUi(true)

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

Aqui estão algumas dicas sobre como evitar problemas ao implementar a autenticação intermediada no Android:

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

• Versão do broker - Instale a versão mínima necessária dos aplicativos do broker . Qualquer um desses dois aplicativos pode ser usado para autenticação intermediada no Android.

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

• Precedência do corretor - O MSAL se comunica com o primeiro broker instalado no dispositivo quando vários brokers são instalados.

  Exemplo: Se instalar primeiro o Microsoft Authenticator e, em seguida, instalar o Portal da Empresa do Intune, a autenticação intermediada só acontecerá no Microsoft Authenticator.

• Logs - Se você encontrar um problema com a autenticação intermediada, a visualização dos logs do broker pode ajudá-lo a diagnosticar a causa.

  • Obtenha os logs do Microsoft Authenticator:

    1. Selecione o botão de menu no canto superior direito do aplicativo.
    2. Selecione Enviar comentários>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 exibe a ID do incidente. Registe o ID do incidente e inclua-o quando 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 Suporte por e-mail de ajuda>.
    3. Para enviar os logs, selecione Carregar somente logs.

    Depois de enviar os logs, uma caixa de diálogo exibe a ID do incidente. Registe o ID do incidente e inclua-o quando solicitar assistência.

Próximos passos

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