Configurar um aplicativo móvel que chama APIs da 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. As aplicações móveis apresentam algumas complexidades relacionadas com a adaptação ao seu quadro de criação.

Bibliotecas da Microsoft que suportam aplicações móveis

As seguintes bibliotecas da Microsoft suportam aplicações móveis:

Plataforma	Projeto em GitHub	Pacote	Como obter começar	Geralmente disponível (GA) ou Pré-visualização^{pública 1}
Android (Java)	MSAL Android	MSAL	Início rápido	GA
Androide (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

1 Os Termos de Licença Universal para Serviços Online aplicam-se às bibliotecas na Pré-visualização Pública.

Instanciar o aplicativo

Android

Os aplicativos móveis usam a PublicClientApplication classe. Veja como instanciá-lo:

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

iOS

Os aplicativos móveis no iOS precisam instanciar a MSALPublicClientApplication classe. Para instanciar a 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 */}

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 instanciar o aplicativo para aplicativos Xamarin.iOS, Xamarin.Android e UWP.

Nota

MSAL.NET versões 4.61.0 e superiores não oferecem suporte para a Plataforma Universal do Windows (UWP), Xamarin Android e Xamarin iOS. Recomendamos que você migre seus aplicativos Xamarin para estruturas modernas como MAUI. Leia mais sobre a descontinuação em Anunciando a próxima substituição do MSAL.NET para Xamarin e UWP.

Instanciar o aplicativo

No Xamarin ou UWP, a maneira mais simples de instanciar o aplicativo é usando o código a seguir. Neste código, ClientId está o GUID do seu aplicativo registrado.

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

Métodos adicionais With<Parameter> definem o pai da interface do usuário, substituem a autoridade padrão, especificam um nome de cliente e uma versão 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 manipular proxies e especificar telemetria e registro.

As seções a seguir fornecem mais informações sobre como instanciar o aplicativo.

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

No Android, passe a atividade pai antes de fazer a autenticação interativa. No iOS, quando você usa um corretor, passe ViewController. Da mesma forma na UWP, talvez você queira passar a janela pai. Você passa quando adquire o token. Mas ao criar o aplicativo, você também pode 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 CurrentActivityPlugino . O código do construtor resultante PublicClientApplication é semelhante a este exemplo:

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

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

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

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

Tarefas para MSAL para iOS e macOS

Estas tarefas são necessárias quando utiliza o MSAL para iOS e macOS:

Tarefas para Xamarin.Android

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

Para obter mais informações, consulte Considerações sobre o Xamarin.Android.

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

Tarefas para UWP

Na 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, consulte Considerações específicas da UWP com MSAL.NET.

Configurar o aplicativo para usar o broker

No Android e iOS, os corretores permitem:

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

Habilitar o broker no Xamarin

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

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

Ativar o broker para MSAL para Android

Para obter informações sobre como habilitar um broker no Android, consulte Autenticação intermediada no Android.

Ativar o broker para MSAL para iOS e macOS

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

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

Habilitar a autenticação intermediada para o Xamarin iOS

Siga as etapas nesta seção para permitir que seu aplicativo Xamarin.iOS converse com o aplicativo Microsoft Authenticator .

Etapa 1: Habilitar o suporte ao broker

O suporte ao corretor está desativado por padrão. Você o habilita para uma classe individual PublicClientApplication . Use o WithBroker() parâmetro ao criar a classe através PublicClientApplicationBuilderdo PublicClientApplication . 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: Atualizar o AppDelegate para lidar com o retorno de chamada

Quando MSAL.NET chama o corretor, ele liga de volta para o seu aplicativo. Ele chama de volta usando o AppDelegate.OpenUrl método. Como o MSAL aguarda a resposta do corretor, seu aplicativo precisa cooperar para chamar MSAL.NET de volta. Você configura esse comportamento atualizando o AppDelegate.cs arquivo 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 de processar a resposta do corretor e concluir o processo de autenticação que MSAL.NET iniciado.

Etapa 3: Definir um UIViewController()

Para o Xamarin iOS, normalmente não é necessário definir uma janela de objeto. Mas, neste caso, você deve configurá-lo para que você possa enviar e receber respostas de um corretor. Para definir uma janela de objeto, no AppDelegate.cs, defina um ViewControllerarquivo .

Para definir a janela de objeto, execute estas etapas:

Em AppDelegate.cs, defina o App.RootViewController para um novo UIViewController(). Essa configuração garante que a chamada para o corretor inclua UIViewController. Se não estiver definido corretamente, 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."

AcquireTokenInteractive Na chamada, use .WithParentActivityOrWindow(App.RootViewController). Passe a referência para a janela de objeto que você usará. Eis um exemplo:

Em App.cs:

   public static object RootViewController { get; set; }

Em AppDelegate.cs:

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

AcquireToken No convite:

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

Etapa 4: Registrar um esquema de URL

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

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

Prefixo CFBundleURLSchemes com msauth.
Adicione CFBundleURLName ao final. Siga este padrão:

$"msauth.(BundleId)"

Aqui, BundleId identifica exclusivamente o 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 receber 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 5: Adicionar à 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, como no exemplo de Info.plist código a seguir:

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

Autenticação intermediada para MSAL para iOS e macOS

A autenticação intermediada é habilitada por padrão para cenários do Microsoft Entra.

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

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

- (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 MSAL no scene:openURLContexts: de UISceneDelegate em vez disso. O MSAL handleMSALResponse:sourceApplication: deve ser chamado apenas uma vez para cada URL.

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

Etapa 2: Registrar um esquema de URL

O MSAL para iOS e macOS 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 Info.plist arquivo.

Para registrar um esquema para seu aplicativo:

Prefira seu esquema de URL personalizado com msauth.
Adicione o identificador do seu pacote ao final do seu esquema. Siga este padrão:

$"msauth.(BundleId)"

Aqui, BundleId identifica exclusivamente o 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 receber a resposta do broker. Certifique-se de que o URI de redirecionamento no formato msauth.(BundleId)://auth está registrado para seu aplicativo.
```
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
```

Etapa 3: Adicionar LSApplicationQueriesSchemes

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

Nota

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

Aqui está um exemplo de como adicionar LSApplicationQueriesSchemes:

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

Autenticação intermediada para Xamarin.Android

Para obter informações sobre como habilitar um broker no Android, consulte Autenticação intermediada no Xamarin.Android.

Próximos passos

Passe para o próximo artigo neste cenário, Adquirindo um token.

Partilhar via

Configurar um aplicativo móvel que chama APIs da Web

Bibliotecas da Microsoft que suportam aplicações móveis

Instanciar o aplicativo

Android

iOS

Xamarin ou UWP

Instanciar o aplicativo

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

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

Habilitar o broker no Xamarin

Ativar o broker para MSAL para Android

Ativar o broker para MSAL para iOS e macOS

Habilitar a autenticação intermediada para o Xamarin iOS

Etapa 1: Habilitar o suporte ao broker

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

Etapa 3: Definir um UIViewController()

Etapa 4: Registrar um esquema de URL

Etapa 5: Adicionar à seção LSApplicationQueriesSchemes

Autenticação intermediada para MSAL para iOS e macOS

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

Etapa 2: Registrar um esquema de URL

Etapa 3: Adicionar LSApplicationQueriesSchemes

Autenticação intermediada para Xamarin.Android

Próximos passos

Comentários

Recursos adicionais