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

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

O 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

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• XCode 10+
• iOS 10+
• macOS 10.12+

Como o exemplo funciona

Etapa 1: Configurar seu aplicativo

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

Etapa 2: Baixar o projeto de exemplo

Etapa 3: Instalar dependências

1. Extraia o arquivo zip.
2. Em uma janela de terminal, navegue até a pasta com 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.

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 do dicionário, substitua Enter_the_bundle_Id_Here pela ID do Pacote que 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 início rápido.

Baixar o 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 a MSAL ao seu aplicativo usando o seguinte processo:

$ vi Podfile

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

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Execute o comando de instalação do CocoaPods:

pod install

Inicializar MSAL

Você pode adicionar a referência para 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 'nil' para usar o valor padrão ou seu URI de redirecionamento personalizado.

Somente para iOS, requisitos de aplicativo adicionais

Seu aplicativo também deve ter o seguinte no AppDelegate. Isso permite que o SDK da MSAL manipule a resposta de token do aplicativo agente de autenticação quando você faz 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)
}

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. O exemplo 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 pode ser obrigado a selecionar sua conta, inserir suas credenciais ou consentir com as permissões do aplicativo. Por exemplo

• A primeira vez que os usuários entrarem no aplicativo
• Se um usuário redefinir sua senha, ele precisará inserir suas credenciais
• Quando seu aplicativo está solicitando acesso a um recurso pela primeira vez
• Quando a MFA ou outras políticas de Acesso Condicional são necessárias

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParameters!)
self.applicationContext!.acquireToken(with: parameters) { (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 APIs Web personalizadas (api://<Application ID>/access_as_user))

acquireTokenSilent: obter um token de acesso silenciosamente

Os aplicativos não devem exigir que seus usuários entrem sempre que solicitam um token. Se o usuário já tiver entrado, esse método permitirá 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. Esse início rápido é sobre um aplicativo de conta única. Se você quiser criar um aplicativo de várias contas, precisará definir a lógica para identificar qual conta usar para solicitações de token usando accountsFromDeviceForParameters:completionBlock: e passando o accountIdentifier correto.

Ajuda e suporte

Se você precisar de ajuda, deseje relatar um problema ou quiser saber mais sobre suas opções de suporte, consulte Ajuda e suporte para desenvolvedores.

Próximas etapas

Vá para o tutorial passo a passo no qual você cria um aplicativo iOS ou macOS que obtém um token de acesso da plataforma de identidade da Microsoft e o usa para chamar a API do Microsoft Graph.