Configurar um aplicativo móvel que chama as APIs Web

Artigo
07/16/2024

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	Geralmente disponíveis (GA) ou Visualização pública¹
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.

Observação

As versões 4.61.0 e superiores do MSAL.NET não oferecem suporte à Plataforma Universal do Windows (UWP), Xamarin Android e Xamarin iOS. Recomendamos que você migre seus aplicativos Xamarin para estruturas modernas, como o MAUI. Leia mais sobre a substituição em Anunciando a substituição futura de MSAL.NET para Xamarin 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:

Tarefas para Xamarin.Android

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

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:

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

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:

Prefixe CFBundleURLSchemes com msauth.
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:

Prefixe seu esquema de URL personalizado com msauth.
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.

Observação

O esquema msauthv3 é necessário quando seu aplicativo é compilado usando o Xcode 11 e posterior.

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.

Compartilhar via

Configurar um aplicativo móvel que chama as APIs Web

Bibliotecas Microsoft com suporte a aplicativos móveis

Criar uma instância do aplicativo

Android

iOS

Xamarin ou UWP

Criar uma instância do aplicativo

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

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

Tarefas para MSAL para iOS e macOS

Tarefas para Xamarin.Android

Tarefas para UWP

Configurar o aplicativo para usar o agente

Habilitar o agente no Xamarin

Habilitar o agente para MSAL para Android

Habilitar o agente para MSAL para iOS e macOS

Habilitar a autenticação agenciada para o Xamarin iOS

Etapa 1: habilitar o suporte ao agente

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

Etapa 3: definir um UIViewController()

Etapa 4: registrar um esquema de URL

Etapa 5: adicionar à seção LSApplicationQueriesSchemes

Autenticação agenciada para MSAL para iOS e macOS

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

Etapa 2: registrar um esquema de URL

Etapa 3: adicionar LSApplicationQueriesSchemes

Autenticação agenciada para Xamarin.Android

Próximas etapas

Comentários

Recursos adicionais