Configurar um aplicativo móvel que chama as APIs Web

Depois de criar seu aplicativo, você aprenderá a configurar o código usando os parâmetros de registro do aplicativo. Os aplicativos móveis apresentam algumas complexidades relacionadas ao ajuste na estrutura de criação.

Bibliotecas Microsoft com suporte a aplicativos móveis

As seguintes bibliotecas da Microsoft dão suporte a aplicativos móveis:

Plataforma	Projeto em GitHub	Pacote	Introdução iniciado	Conectar usuários	Acessar APIs da Web	Geralmente disponíveis (GA) ou Visualização pública1
Android (Java)	MSAL Android	MSAL	Início rápido			GA
Android (Kotlin)	MSAL Android	MSAL	—			GA
iOS (Swift/Obj-C)	MSAL para iOS e macOS	MSAL	Tutorial			GA
Xamarin (.NET)	MSAL.NET	Microsoft.Identity.Client	—			GA

¹ Os Termos de Licença Universal para Serviços Online se aplicam a bibliotecas em Visualização Pública.

Criar uma instância do aplicativo

Android

Os aplicativos móveis usam a classe PublicClientApplication. Veja como criar uma instância dele:

PublicClientApplication sampleApp = new PublicClientApplication(
                    this.getApplicationContext(),
                    R.raw.auth_config);

iOS

Os aplicativos móveis no iOS precisam criar uma instância da classe MSALPublicClientApplication. Para criar uma instância da classe, use o código a seguir.

NSError *msalError = nil;

MSALPublicClientApplicationConfig *config = [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"];
MSALPublicClientApplication *application = [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&msalError];

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>")
if let application = try? MSALPublicClientApplication(configuration: config){ /* Use application */}

As propriedades MSALPublicClientApplicationConfig adicionais podem substituir a autoridade padrão, especificar um URI de redirecionamento ou alterar o comportamento do cache de token MSAL.

Xamarin ou UWP

Esta seção explica como criar uma instância do aplicativo para aplicativos Xamarin.iOS, Xamarin.Android e UWP.

Criar uma instância do aplicativo

No Xamarin ou UWP, a maneira mais simples de criar uma instância do aplicativo é usando o código a seguir. Nesse código, ClientId é o GUID do seu aplicativo registrado.

var app = PublicClientApplicationBuilder.Create(clientId)
                                        .Build();

Os métodos With<Parameter> adicionais definem o pai da interface do usuário, substituem a autoridade padrão, especificam um nome e uma versão do cliente para telemetria, especificam um URI de redirecionamento e especificam a fábrica HTTP a ser usada. A fábrica HTTP pode ser usada, por exemplo, para lidar com proxies e para especificar a telemetria e o registro em log.

As seções a seguir fornecem mais informações sobre como criar uma instância do aplicativo.

Especificar a interface do usuário pai, a janela ou a atividade

No Android, passe a atividade pai antes de fazer a autenticação interativa. No iOS, quando você usa um agente, passe ViewController. Da mesma forma no UWP, talvez você queira passar a janela pai. Você a passa quando adquire o token. Mas quando você estiver criando o aplicativo, também poderá especificar um retorno de chamada como um delegado que retorna UIParent.

IPublicClientApplication application = PublicClientApplicationBuilder.Create(clientId)
  .ParentActivityOrWindowFunc(() => parentUi)
  .Build();

No Android, recomendamos que você use o CurrentActivityPlugin. O código do construtor PublicClientApplication resultante é semelhante a este exemplo:

// Requires MSAL.NET 4.2 or above
var pca = PublicClientApplicationBuilder
  .Create("<your-client-id-here>")
  .WithParentActivityOrWindow(() => CrossCurrentActivity.Current)
  .Build();

Encontrar mais parâmetros de criação de aplicativos

Para obter uma lista de todos os métodos disponíveis no PublicClientApplicationBuilder, consulte a Lista de métodos.

Para obter uma descrição de todas as opções que são expostas no PublicClientApplicationOptions, consulte a documentação de referência.

Tarefas para MSAL para iOS e macOS

Essas tarefas são necessárias quando você usa o MSAL para iOS e macOS:

• Implementar o retorno de chamada openURL
• Habilitar grupos de acesso ao conjunto de chaves
• Personalizar navegadores e WebViews

Tarefas para Xamarin.Android

Se você usar o Xamarin.Android, execute as seguintes tarefas:

• Verifique se o controle retorna ao MSAL após a parte interativa do fluxo de autenticação terminar
• Atualizar o manifesto do Android
• Usar a exibição da Web inserida (opcional)
• Solucione problemas conforme necessário

Para obter mais informações, confira as Considerações sobre Xamarin.Android.

Para obter considerações sobre os navegadores no Android, confira Considerações específicas do Xamarin.Android com o MSAL.NET.

Tarefas para UWP

No UWP, você pode usar redes corporativas. As seções a seguir explicam as tarefas que você deve concluir no cenário corporativo.

Para obter mais informações, confira Considerações específicas de UWP com MSAL.NET.

Configurar o aplicativo para usar o agente

No Android e no iOS, os agentes habilitam:

• Logon único (SSO): você pode usar o SSO nos dispositivos registrados com a ID do Microsoft Entra. Quando você usa o SSO, os usuários não precisam entrar em cada aplicativo.
• Identificação do dispositivo: essa configuração habilita as políticas de acesso condicional relacionadas aos dispositivos do Microsoft Entra. O processo de autenticação usa o certificado de dispositivo que foi criado quando o dispositivo foi ingressado no local de trabalho.
• Verificação da identificação do aplicativo: quando um aplicativo chama o agente, ele passa sua URL de redirecionamento. Em seguida, o agente a verifica.

Habilitar o agente no Xamarin

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

Para habilitar a autenticação agenciada para o Xamarin.iOS, siga as etapas na seção Xamarin.iOS deste artigo.

Habilitar o agente para MSAL para Android

Para obter informações sobre como habilitar um agente no Android, confira Autenticação agenciada no Android.

Habilitar o agente para MSAL para iOS e macOS

A autenticação agenciada está habilitada por padrão nos cenários do Microsoft Entra no MSAL para iOS e macOS.

As seções a seguir fornecem instruções para configurar seu aplicativo para o suporte à autenticação agenciada para MSAL para Xamarin.iOS ou MSAL para iOS e macOS. Nos dois conjuntos de instruções, algumas das etapas são diferentes.

Habilitar a autenticação agenciada para o Xamarin iOS

Siga as etapas nesta seção para habilitar seu aplicativo Xamarin.iOS para se comunicar com o aplicativo Microsoft Authenticator.

Etapa 1: habilitar o suporte ao agente

O suporte ao agente é desabilitado por padrão. Você o habilita para uma classe PublicClientApplication individual. Use o parâmetro WithBroker() ao criar a classe PublicClientApplication por meio de PublicClientApplicationBuilder. 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: atualizar o AppDelegate para manipular o retorno de chamada

Quando o MSAL.NET chama o agente, o agente chama de volta para o seu aplicativo. Ele chama de volta usando o método AppDelegate.OpenUrl. Como o MSAL aguarda a resposta do agente, seu aplicativo precisa cooperar para chamar MSAL.NET de volta. Você configura esse comportamento atualizando o arquivo AppDelegate.cs para substituir o método, como mostra o código 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. É uma oportunidade para processar a resposta do agente e concluir o processo de autenticação que o MSAL.NET iniciou.

Etapa 3: definir um UIViewController()

Para o Xamarin iOS, normalmente você não precisa definir uma janela de objeto. Mas, nesse caso, você deve defini-la para que possa enviar e receber respostas de um agente. Para definir uma janela de objeto, no AppDelegate.cs, você define um ViewController.

Para definir a janela de objeto, siga estas etapas:

1. No AppDelegate.cs, defina o App.RootViewController para um novo UIViewController(). Essa configuração garante que a chamada para o agente inclua UIViewController. 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). Passe a referência à janela de objeto que você usará. Veja um exemplo:

   Em App.cs:

      public static object RootViewController { get; set; }
   

   Em AppDelegate.cs:

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

   Na chamada AcquireToken:

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

Etapa 4: registrar um esquema de URL

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

Para registrar o esquema de URL do seu aplicativo, siga estas etapas:

1. Prefixe CFBundleURLSchemes com msauth.

2. Adicione CFBundleURLName ao final. Siga este padrão:

   $"msauth.(BundleId)"

   Aqui, BundleId identifica exclusivamente seu dispositivo. Por exemplo, se BundleId for yourcompany.xforms, seu esquema de URL é msauth.com.yourcompany.xforms.

   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 5: adicionar à 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, como no exemplo de código a seguir:

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

Autenticação agenciada para MSAL para iOS e macOS

A autenticação agenciada está habilitada por padrão nos cenários do Microsoft Entra.

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

Quando o MSAL para iOS e macOS chama o agente, o agente chama de volta para seu aplicativo usando o método openURL. Como o MSAL aguarda a resposta do agente, seu aplicativo precisa cooperar para chamar o MSAL de volta. Configure essa capacidade atualizando o arquivo AppDelegate.m para substituir o método, como os exemplos de código a seguir mostram.

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [MSALPublicClientApplication handleMSALResponse:url
                                         sourceApplication:options[UIApplicationOpenURLOptionsSourceApplicationKey]];
}

    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

        guard let sourceApplication = options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String else {
            return false
        }

        return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApplication)
    }

Se você adotou UISceneDelegate no iOS 13 ou posterior, coloque o retorno de chamada do MSAL no scene:openURLContexts: de UISceneDelegate em vez disso. O handleMSALResponse:sourceApplication: do MSAL deve ser chamado apenas uma vez para cada URL.

Para obter mais informações, confira a documentação da Apple.

Etapa 2: registrar um esquema de URL

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

Para registrar um esquema para seu aplicativo:

1. Prefixe seu esquema de URL personalizado com msauth.

2. Adicione seu identificador de pacote ao final do seu esquema. Siga este padrão:

   $"msauth.(BundleId)"

   Aqui, BundleId identifica exclusivamente seu dispositivo. Por exemplo, se BundleId for yourcompany.xforms, seu esquema de URL é msauth.com.yourcompany.xforms.

   Esse esquema de URL se tornará parte do URI de redirecionamento que identifica exclusivamente seu aplicativo quando ele recebe a resposta do agente. Certifique-se de que o URI de redirecionamento no formato msauth.(BundleId)://auth esteja registrado para o seu aplicativo.

   <key>CFBundleURLTypes</key>
   <array>
       <dict>
           <key>CFBundleURLSchemes</key>
           <array>
               <string>msauth.[BUNDLE_ID]</string>
           </array>
       </dict>
   </array>
   

Etapa 3: adicionar LSApplicationQueriesSchemes

Adicione LSApplicationQueriesSchemes para permitir chamadas para o aplicativo Microsoft Authenticator, se ele estiver instalado.

Este é um exemplo de como adicionar LSApplicationQueriesSchemes:

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

Autenticação agenciada para Xamarin.Android

Para obter informações sobre como habilitar um agente no Android, confira Autenticação agenciada no Xamarin.Android.

Próximas etapas

Vá para o próximo artigo nesse cenário, Adquirir um token.