Configurar um aplicativo móvel que chama as APIs Web

Aplica-se a: Locatários da força de trabalho (saiba mais)

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 extras relacionadas à adaptação à estrutura de criação.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente. Essa conta deve ter permissões para gerenciar aplicativos. Use qualquer uma das seguintes funções necessárias para registrar o aplicativo:
  • Administrador de aplicativos
  • Desenvolvedor de aplicativos
• Registre um novo aplicativo no Centro de administração do Microsoft Entra, configurado apenas para Contas neste diretório organizacional. Consulte Registrar um aplicativo para obter mais detalhes. Registre os seguintes valores na página visão geral do aplicativo para uso posterior:
  • ID do aplicativo (cliente)
  • ID do diretório (locatário)

Adicionar um URI de redirecionamento de plataforma

Para especificar o tipo de aplicativo para o registro do aplicativo, siga estas etapas:

1. Em Gerenciar, selecione Autenticação>Adicionar uma plataforma>iOS/macOS.
2. Insira a ID do pacote e selecione Configurar. O URI de redirecionamento é computado para você.

Se preferir configurar manualmente o URI de redirecionamento, você poderá fazer isso por meio do manifesto do aplicativo. Este é o formato recomendado para o manifesto:

• iOS:msauth.<BUNDLE_ID>://auth
  • Por exemplo, digite msauth.com.yourcompany.appName://auth
• Androide: msauth://<PACKAGE_NAME>/<SIGNATURE_HASH>
  • Para gerar o hash de assinatura do Android, use a chave de versão ou a chave de depuração por meio do comando KeyTool.

Habilitar fluxo de cliente público

Quando o aplicativo usa apenas a autenticação de nome de usuário e senha, não é preciso registrar um URI de redirecionamento para ele. Esse fluxo faz uma viagem de ida e volta para a plataforma de identidade da Microsoft. O aplicativo não será chamado de volta em nenhum URI específico. Mas você deve habilitar o fluxo de cliente público.

Para identificar seu aplicativo como um cliente público, siga estas etapas:

1. Em Gerenciar, selecione Autenticação.

2. Em Configurações avançadas, na opção Permitir fluxos de clientes públicos, selecione Sim.

3. Selecione Salvar para salvar as alterações.

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

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

UWP

Esta seção explica como instanciar o aplicativo para aplicativos UWP.

Criar uma instância do aplicativo

Na UWP, a maneira mais simples de instanciar o 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 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 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 suporte de autenticação agenciada para iOS e macOS. Nos dois conjuntos de instruções, algumas das etapas são diferentes.

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>

Próximas etapas

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