Configurar um aplicativo móvel que chama APIs da Web

Aplica-se a: Inquilinos 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. As aplicações móveis apresentam algumas complexidades adicionais relacionadas com a adaptação à sua 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
  • Programador de Aplicações
• Registre um novo aplicativo no centro de administração do Microsoft Entra, configurado para Contas somente neste diretório organizacional. Consulte Registar uma candidatura para obter mais detalhes. Registre os seguintes valores na página Visão geral do aplicativo para uso posterior:
  • ID da aplicação (cliente)
  • ID do diretório (inquilino)

Adicionar um URI de redirecionamento de plataforma

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

1. Em Gerir, selecione Autenticação >Adicionar uma plataforma>iOS/macOS.
2. Introduza o ID do pacote e, em seguida, selecione Configurar. O URI de redirecionamento é calculado para você.

Se preferir configurar manualmente o URI de redirecionamento, você pode fazê-lo por meio do manifesto do aplicativo. Aqui está o formato recomendado para o manifesto:

• iOS:msauth.<BUNDLE_ID>://auth
  • Por exemplo, insira msauth.com.yourcompany.appName://auth
• Android: msauth://<PACKAGE_NAME>/<SIGNATURE_HASH>
  • Você pode gerar o hash da assinatura do Android usando a chave de liberação ou a chave de depuração através do comando KeyTool.

Habilitar o fluxo público de clientes

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

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

1. Em Gerir, selecione Autenticação.

2. Em Configurações avançadas, para Permitir fluxos de clientes públicos, selecione Sim.

3. Selecione Guardar para guardar as alterações.

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	Iniciar sessão de utilizadores	Aceder a APIs Web	Geralmente disponível (GA) ou Pré-visualização pública1
Android (Java)	MSAL Android	MSAL	Início rápido			disponibilidade geral
Androide (Kotlin)	MSAL Android	MSAL	—			disponibilidade geral
iOS (Swift/OBJ-C)	MSAL para iOS e macOS	MSAL	Tutoriais			disponibilidade geral

¹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 */}

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

UWP

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

Instanciar o aplicativo

Na 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

Em Android, passe a atividade pai antes de realizar a autenticação interativa. No iOS, quando utilizas um corretor, introduz ViewController. Da mesma forma, talvez na UWP tu queiras passar a janela pai. Você o fornece quando adquire o token. Mas ao criar a aplicação, 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 utilizes CurrentActivityPlugin. 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 de 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:

• Implementar a openURL função de retorno
• Habilitar grupos de acesso às chaves
• Personalizar navegadores e WebViews

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.

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 iOS e macOS. Nos dois conjuntos de instruções, algumas das etapas diferem.

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 a sua aplicação usando o método openURL. 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:

1. Prefixe o seu esquema de URL personalizado com msauth.

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

Próximos passos

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