Início Rápido: Conectar usuários e chamar a API do Microsoft Graph de um aplicativo iOS ou macOS

  • Artigo

Seja bem-vindo! Essa provavelmente não é a página que você esperava. Enquanto trabalhamos em uma correção, este link direcionará você para o artigo certo:

Início Rápido: entre com os usuários e chame o Microsoft Graph a partir de um aplicativo iOS ou macOS

Pedimos desculpas pela inconveniência e agradecemos sua paciência enquanto trabalhamos para resolver isso.

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

Mostra como o aplicativo de exemplo gerado por este início rápido funciona

Etapa 1: Configurar seu aplicativo

Para que o exemplo de código deste guia de início rápido funcione, adicione um URI de Redirecionamento compatível com o agente de autenticação.

Fazer essa alteração para mim

Já configurado Seu aplicativo já está configurado com esses atributos

Etapa 2: Baixar o projeto de exemplo

Baixar o exemplo de código para iOS

Baixar o exemplo de código para macOS

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: seu aplicativo está configurado e pronto para ser executado

Configuramos seu projeto com os valores das propriedades do aplicativo e ele está pronto para ser executado.

Observação

Enter_the_Supported_Account_Info_Here

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

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

  3. Abra as configurações do projeto. Na seção Identidade, insira o Identificador do Pacote que você inseriu no portal.

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

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

  6. 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 que estão sendo solicitados (ou seja, [ "user.read" ] para o Microsoft Graph ou [ "<Application ID URL>/scope" ] para as 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