Início Rápido: logar usuários e chamar o Microsoft Graph em um aplicativo iOS ou macOS

  • Artigo

Neste guia de início rápido, você baixará e executará um exemplo de código que demonstra como um aplicativo iOS ou macOS nativo pode conectar usuários e obter um token de acesso para chamar a API do Microsoft Graph.

O guia de início rápido se aplica a aplicativos iOS e macOS. Algumas etapas são necessárias apenas para aplicativos iOS e serão indicadas como tal.

Pré-requisitos

Como o exemplo funciona

Diagrama mostrando como o aplicativo de exemplo gerado por este início rápido funciona.

Registrar seu aplicativo de início rápido

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à solução manualmente, siga estas etapas:

  1. Faça login no Centro de administração do Microsoft Entra como pelo menos um Desenvolvedor de aplicativos.
  2. Se você tiver acesso a vários locatários, use o ícone de Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.
  3. Navegue até Identidade>Aplicativos>Registros do aplicativo.
  4. Selecione Novo registro.
  5. Insira um Nome para seu aplicativo. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
  6. Selecione Registrar.
  7. Em Gerenciar, selecione Autenticação>Adicionar Plataforma>iOS.
  8. Insira o Identificador de pacote para seu aplicativo. O identificador de pacote é uma cadeia de caracteres exclusiva que identifica exclusivamente seu aplicativo, por exemplo, com.<yourname>.identitysample.MSALMacOS. Anote o valor que for usado. Observe que a configuração do iOS também é aplicável a aplicativos macOS.
  9. Selecione Configurar e salve os detalhes da Configuração da MSAL para uso posterior neste guia de início rápido.
  10. Selecione Concluído.

Etapa 2: Baixar o projeto de exemplo

Etapa 3: Instalar dependências

  1. Extraia o arquivo zip.
  2. Em uma janela do terminal, navegue até a pasta que contém o exemplo de código baixado e execute pod install para instalar a biblioteca MSAL mais recente.

Etapa 4: Configurar seu projeto

Se você tiver selecionado a Opção 1 acima, poderá ignorar essas etapas.

  1. Abra o projeto no XCode.

  2. Edite ViewController.swift e substitua a linha que começa com 'let kClientID' pelo seguinte snippet de código. Lembre-se de atualizar o valor de kClientID com a ID do cliente que você salvou quando registrou seu aplicativo anteriormente neste início rápido:

    let kClientID = "Enter_the_Application_Id_Here"

  3. Se você estiver criando um aplicativo para nuvens nacionais do Microsoft Entra, substitua a linha que começa com 'let kGraphEndpoint' e 'let kAuthority' pelos pontos de extremidade corretos. Para acesso global, use valores padrão:

    let kGraphEndpoint = "https://graph.microsoft.com/"
let kAuthority = "https://login.microsoftonline.com/common"

  4. Outros pontos de extremidade estão documentados aqui. Por exemplo, para executar o início rápido com o Microsoft Entra Alemanha, use o seguinte:

    let kGraphEndpoint = "https://graph.microsoft.de/"
let kAuthority = "https://login.microsoftonline.de/common"

  5. Abra as configurações do projeto. Na seção Identidade, insira o Identificador de pacote.

  6. Clique com o botão direito do mouse em Info.plist e selecione Abrir Como>Código-Fonte.

  7. No nó raiz dict, substitua Enter_the_bundle_Id_Here pela ID do Pacoteque você usou no portal. Observe o prefixo msauth. na cadeia de caracteres.

    <key>CFBundleURLTypes</key>
<array>
   <dict>
      <key>CFBundleURLSchemes</key>
      <array>
         <string>msauth.Enter_the_Bundle_Id_Here</string>
      </array>
   </dict>
</array>

  8. Compile e execute o aplicativo.

Mais informações

Leia estas seções para saber mais sobre este guia de início rápido.

Obter MSAL

MSAL (MSAL.framework) é a biblioteca usada para conectar usuários e solicitar tokens usados para acessar uma API protegida pela plataforma de identidade da Microsoft. Você pode adicionar s MSAL ao seu aplicativo usando o seguinte processo:

$ vi Podfile

Adicione o seguinte a esse podfile (com o destino do seu projeto):

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Execute o comando de instalação do CocoaPods:

pod install

Inicializar a MSAL

Você pode adicionar a referência da MSAL adicionando o seguinte código:

import MSAL

Em seguida, inicialize a MSAL usando o seguinte código:

let authority = try MSALAADAuthority(url: URL(string: kAuthority)!)

let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
Em que: Descrição
clientId A ID do aplicativo registrado em portal.azure.com
authority A plataforma de identidade da Microsoft. Na maioria dos casos, ele estará em https://login.microsoftonline.com/common
redirectUri O URI de redirecionamento do aplicativo. Você pode passar “nulo” para usar o valor padrão ou o URI de redirecionamento personalizado.

Somente para o iOS, requisitos adicionais do aplicativo

Seu aplicativo também deve ter o seguinte no AppDelegate. Isso permite que o SDK da MSAL lide com a resposta de token do aplicativo do agente de autenticação quando você efetuar a autenticação.

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

    return MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: options[UIApplication.OpenURLOptionsKey.sourceApplication] as? String)
}

Observação

No iOS 13 +, se você adotar UISceneDelegate em vez de UIApplicationDelegate, coloque esse código no retorno de chamada scene:openURLContexts: (confira a Documentação da Apple). Se você der suporte a UISceneDelegate e UIApplicationDelegate para compatibilidade com o iOS mais antigo, o retorno de chamada da MSAL precisará ser colocado nos dois locais.

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {

   guard let urlContext = URLContexts.first else {
      return
   }

   let url = urlContext.url
   let sourceApp = urlContext.options.sourceApplication

   MSALPublicClientApplication.handleMSALResponse(url, sourceApplication: sourceApp)
}

Por fim, seu aplicativo precisa ter uma entrada LSApplicationQueriesSchemes em Info.plist junto com CFBundleURLTypes. A amostra vem com isso incluído.

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

Conectar usuários e solicitar tokens

A MSAL tem dois métodos usados para adquirir tokens: acquireToken e acquireTokenSilent.

acquireToken: Obter um token interativamente

Algumas situações exigem que os usuários interajam com a plataforma de identidade da Microsoft. Nesses casos, o usuário final talvez precise selecionar sua conta, inserir suas credenciais ou dar consentimento às permissões do seu aplicativo. Por exemplo,

  • A primeira vez que os usuários entram no aplicativo
  • Se um usuário redefinir a senha, ele precisará inserir as credenciais
  • Quando seu aplicativo estiver solicitando acesso a um recurso pela primeira vez
  • Quando a MFA ou outras políticas de Acesso Condicional forem necessárias
let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}
Em que: Descrição
scopes Contém os escopos solicitados (ou seja, [ "user.read" ] para Microsoft Graph ou [ "<Application ID URL>/scope" ] para APIs Web personalizadas (api://<Application ID>/access_as_user))

acquireTokenSilent: Obter um token de acesso silenciosamente

Os aplicativos não deverão exigir que seus usuários entrem sempre que solicitarem um token. Se o usuário já está conectado, esse método permite que os aplicativos solicitem tokens silenciosamente.

self.applicationContext!.getCurrentAccount(with: nil) { (currentAccount, previousAccount, error) in

   guard let account = currentAccount else {
      return
   }

   let silentParams = MSALSilentTokenParameters(scopes: self.kScopes, account: account)
   self.applicationContext!.acquireTokenSilent(with: silentParams) { (result, error) in /* Add your handling logic */}
}
Em que: Descrição
scopes Contém os escopos solicitados (ou seja, [ "user.read" ] para Microsoft Graph ou [ "<Application ID URL>/scope" ] para APIs Web personalizadas (api://<Application ID>/access_as_user))
account A conta para a qual um token está sendo solicitado. Este é um guia de início rápido sobre um aplicativo de conta única. Se quiser criar um aplicativo de várias contas, você precisará definir a lógica para identificar qual conta usar em solicitações de token usando accountsFromDeviceForParameters:completionBlock: e passando o accountIdentifier correto

Ajuda e suporte

Se precisar de ajuda, quiser relatar um problema ou desejar saber mais sobre as opções de suporte, confira Ajuda e suporte para desenvolvedores.

Próximas etapas

Prossiga para o tutorial passo a passo, em que você criará um aplicativo iOS ou macOS que obtém um token de acesso da plataforma de identidade da Microsoft e o utilizará para chamar a API do Microsoft Graph.

Tutorial: Conectar usuários e chamar o Microsoft Graph em um aplicativo iOS ou macOS