Início Rápido: Conectar usuários e chamar a API do Microsoft Graph de um aplicativo iOS ou macOSQuickstart: Sign in users and call the Microsoft Graph API from an iOS or macOS app

Este início rápido contém um exemplo de código que demonstra como um aplicativo nativo iOS ou macOS pode conectar contas corporativas, pessoais ou de estudante, obter um token de acesso e chamar a API do Microsoft Graph.This quickstart contains a code sample that demonstrates how a native iOS or macOS application can sign in personal, work and school accounts, get an access token, and call the Microsoft Graph API.

Este início rápido se aplica a aplicativos iOS e macOS.This quickstart applies to both iOS and macOS apps. Algumas etapas são necessárias apenas para aplicativos iOS.Some steps are needed only for iOS apps. Essas etapas destacam que se aplicam somente ao iOS.Those steps call out that they are only for iOS.

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

Observação

Pré-requisitosPrerequisites

  • XCode 10+XCode 10+
  • iOS 10+iOS 10+
  • macOS 10.12+macOS 10.12+

Registrar e baixar o aplicativo de início rápidoRegister and download your quickstart app

Você tem duas opções para iniciar o aplicativo de início rápido:You have two options to start your quickstart application:

Opção 1: Registrar e configurar automaticamente o aplicativo e, em seguida, baixar o exemplo de códigoOption 1: Register and auto configure your app and then download the code sample

Etapa 1: Registre seu aplicativoStep 1: Register your application

Para registrar seu aplicativo,To register your app,

  1. Acesse o novo painel do portal do Azure – Registros de aplicativo.Go to the new Azure portal - App registrations pane.
  2. Insira um nome para seu aplicativo e selecione Registrar.Enter a name for your application and select Register.
  3. Siga as instruções para baixar e configurar automaticamente o novo aplicativo com apenas um clique.Follow the instructions to download and automatically configure your new application with just one click.

Opção 2: Registrar e configurar manualmente o aplicativo e o exemplo de códigoOption 2: Register and manually configure your application and code sample

Etapa 1: Registre seu aplicativoStep 1: Register your application

Para registrar seu aplicativo e adicionar as informações de registro do aplicativo à solução manualmente, siga estas etapas:To register your application and add the app's registration information to your solution manually, follow these steps:

  1. Navegue até a página Registros de aplicativo da plataforma de identidade da Microsoft para desenvolvedores.Navigate to the Microsoft identity platform for developers App registrations page.
  2. Selecione Novo registro.Select New registration.
  3. Quando a página Registrar um aplicativo for exibida, insira as informações de registro do aplicativo:When the Register an application page appears, enter your application's registration information:
    • Na seção Nome, insira um nome de aplicativo relevante que será exibido aos usuários do aplicativo quando eles se conectarem ou derem consentimento ao aplicativo.In the Name section, enter a meaningful application name that will be displayed to users of the app when they sign in or consent to your app.
    • Ignore outras configurações nesta página.Skip other configurations on this page.
    • Selecione Register.Select Register.
  4. Na seção Gerenciar, selecione Authentication > Add Platform > iOS.In the Manage section, select Authentication > Add Platform > iOS.
    • Insira o Identificador de pacote para seu aplicativo.Enter the Bundle Identifier for your application. O identificador de pacote é apenas uma cadeia de caracteres exclusiva que identifica exclusivamente seu aplicativo, por exemplo, com.<yourname>.identitysample.MSALMacOS.The bundle identifier is just a unique string that uniquely identifies your application, for example com.<yourname>.identitysample.MSALMacOS. Anote o valor que for usado.Make a note of the value you use.
    • Observe que a configuração do iOS também é aplicável a aplicativos macOS.Note that the iOS configuration is also applicable to macOS applications.
  5. Selecione Configure e salve os detalhes da Configuração da MSAL para uso posterior neste início rápido.Select Configure and save the MSAL Configuration details for later in this quickstart.

Etapa 1: Configurar seu aplicativoStep 1: Configure your application

Para que o exemplo de código deste Início Rápido funcione, é necessário adicionar um URI de redirecionamento compatível com o Agente de autenticação.For the code sample for this quickstart to work, you need to add a redirect URI compatible with the Auth broker.

Já configurado Seu aplicativo já está configurado com esses atributosAlready configured Your application is configured with these attributes

Etapa 2: Baixar o projeto de exemploStep 2: Download the sample project

Etapa 3: Instalar dependênciasStep 3: Install dependencies

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.In a terminal window, navigate to the folder with the downloaded code sample and run pod install to install the latest MSAL library.

Etapa 4: Configurar seu projetoStep 4: Configure your project

Se você tiver selecionado a Opção 1 acima, poderá ignorar essas etapas.If you selected Option 1 above, you can skip these steps.

  1. Extraia o arquivo zip e abra o projeto no XCode.Extract the zip file and open the project in XCode.

  2. Edite ViewController.swift e substitua a linha que começa com 'let kClientID' pelo seguinte snippet de código.Edit ViewController.swift and replace the line starting with 'let kClientID' with the following code snippet. Lembre-se de atualizar o valor de kClientID com a ID do cliente que você salvou quando registrou seu aplicativo no portal anteriormente no início rápido:Remember to update the value for kClientID with the client ID that you saved when you registered your app in the portal earlier in the quickstart:

    let kClientID = "Enter_the_Application_Id_Here"
    
  3. Abra as configurações do projeto.Open the project settings. Na seção Identidade, insira o Identificador do Pacote que você inseriu no portal.In the Identity section, enter the Bundle Identifier that you entered into the portal.

  4. Somente para o iOS, clique com o botão direito do mouse em Info.plist e selecione Abrir como > Código-fonte.For iOS only, right-click Info.plist and select Open As > Source Code.

  5. Somente para o iOS, no nó raiz do dict, substitua CFBundleURLSchemes pela ID do Pacote que você inseriu no portal.For iOS only, under the dict root node, replace CFBundleURLSchemes with the Bundle Id that you entered in the portal.

    <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.Build & run the app!

Observação

Este início rápido dá suporte a Enter_the_Supported_Account_Info_Here.This quickstart supports Enter_the_Supported_Account_Info_Here.

  1. Extraia o arquivo zip e abra o projeto no XCode.Extract the zip file and open the project in XCode.

  2. Edite ViewController.swift e substitua a linha que começa com 'let kClientID' pelo seguinte snippet de código.Edit ViewController.swift and replace the line starting with 'let kClientID' with the following code snippet. Lembre-se de atualizar o valor de kClientID com a ID do cliente que você salvou quando registrou seu aplicativo no portal anteriormente neste início rápido:Remember to update the value for kClientID with the clientID that you saved when you registered your app in the portal earlier in this quickstart:

    let kClientID = "Enter_the_Application_Id_Here"
    
  3. Abra as configurações do projeto.Open the project settings. Na seção Identidade, insira o Identificador do Pacote que você inseriu no portal.In the Identity section, enter the Bundle Identifier that you entered into the portal.

  4. Somente para o iOS, clique com o botão direito do mouse em Info.plist e selecione Abrir como > Código-fonte.For iOS only, right-click Info.plist and select Open As > Source Code.

  5. Somente para o iOS, no nó raiz do dict, substitua Enter_the_bundle_Id_Here pela ID do Pacote que você usou no portal.For iOS only, under the dict root node, replace Enter_the_bundle_Id_Here with the Bundle Id that you used in the portal.

    <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.Build & run the app!

Mais informaçõesMore Information

Leia estas seções para saber mais sobre este guia de início rápido.Read these sections to learn more about this quickstart.

Obter MSALGet 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.MSAL (MSAL.framework) is the library used to sign in users and request tokens used to access an API protected by Microsoft identity platform. Você pode adicionar s MSAL ao seu aplicativo usando o seguinte processo:You can add MSAL to your application using the following process:

$ vi Podfile

Adicione o seguinte a esse podfile (com o destino do seu projeto):Add the following to this podfile (with your project's target):

use_frameworks!

target 'MSALiOS' do
   pod 'MSAL'
end

Execute o comando de instalação do CocoaPods:Run CocoaPods installation command:

pod install

Inicializar a MSALInitialize MSAL

Você pode adicionar a referência da MSAL adicionando o seguinte código:You can add the reference for MSAL by adding the following code:

import MSAL

Em seguida, inicialize a MSAL usando o seguinte código:Then, initialize MSAL using the following code:

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:Where:
clientId A ID do aplicativo registrado em portal.azure.comThe Application ID from the application registered in portal.azure.com
authority O ponto de extremidade da plataforma de identidade da Microsoft.The Microsoft identity platform endpoint. Na maioria dos casos ele será https://login.microsoftonline.com/commonIn most of cases this will be https://login.microsoftonline.com/common
redirectUri O URI de redirecionamento do aplicativo.The redirect URI of the application. Você pode passar “nulo” para usar o valor padrão ou o URI de redirecionamento personalizado.You can pass 'nil' to use the default value, or your custom redirect URI.

Somente para o iOS, requisitos adicionais do aplicativoFor iOS only, additional app requirements

Seu aplicativo também deve ter o seguinte no AppDelegate.Your app must also have the following in your 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.This lets MSAL SDK handle token response from the Auth broker app when you do authentication.

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).On iOS 13+, if you adopt UISceneDelegate instead of UIApplicationDelegate, place this code into the scene:openURLContexts: callback instead (See Apple's documentation). 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.If you support both UISceneDelegate and UIApplicationDelegate for compatibility with older iOS, MSAL callback needs to be placed into both places.

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 deve ter uma entrada LSApplicationQueriesSchemes em Info.plist junto com CFBundleURLTypes.Finally, your app must have an LSApplicationQueriesSchemes entry in your Info.plist alongside the CFBundleURLTypes. A amostra vem com isso incluído.The sample comes with this included.

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

Conectar usuários e solicitar tokensSign in users & request tokens

A MSAL tem dois métodos usados para adquirir tokens: acquireToken e acquireTokenSilent.MSAL has two methods used to acquire tokens: acquireToken and acquireTokenSilent.

acquireToken: Obter um token interativamenteacquireToken: Get a token interactively

Algumas situações exigem que os usuários interajam com a plataforma de identidade da Microsoft.Some situations require users to interact with Microsoft identity platform. Nesses casos, o usuário final talvez precise selecionar sua conta, inserir suas credenciais ou dar consentimento às permissões do seu aplicativo.In these cases, the end user may be required to select their account, enter their credentials, or consent to your app's permissions. Por exemplo,For example,

  • A primeira vez que os usuários entram no aplicativoThe first time users sign in to the application
  • Se um usuário redefinir a senha, ele precisará inserir as credenciaisIf a user resets their password, they'll need to enter their credentials
  • Quando seu aplicativo estiver solicitando acesso a um recurso pela primeira vezWhen your application is requesting access to a resource for the first time
  • Quando a MFA ou outras políticas de Acesso Condicional forem necessáriasWhen MFA or other Conditional Access policies are required
let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}
Em que:Where:
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))Contains the scopes being requested (that is, [ "user.read" ] for Microsoft Graph or [ "<Application ID URL>/scope" ] for custom Web APIs (api://<Application ID>/access_as_user)

acquireTokenSilent: Obter um token de acesso silenciosamenteacquireTokenSilent: Get an access token silently

Os aplicativos não deverão exigir que seus usuários entrem sempre que solicitarem um token.Apps shouldn't require their users to sign in every time they request a token. Se o usuário já está conectado, esse método permite que os aplicativos solicitem tokens silenciosamente.If the user has already signed in, this method allows apps to request tokens silently.

guard let account = try self.applicationContext!.allAccounts().first else { return }
        
let silentParams = MSALSilentTokenParameters(scopes: kScopes, account: account)
self.applicationContext!.acquireTokenSilent(with: silentParams) { (result, error) in /* Add your handling logic */}
Em que:Where:
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))Contains the scopes being requested (that is, [ "user.read" ] for Microsoft Graph or [ "<Application ID URL>/scope" ] for custom Web APIs (api://<Application ID>/access_as_user)
account A conta para a qual um token está sendo solicitado.The account a token is being requested for. Este é um guia de início rápido sobre um aplicativo de conta única.This quickstart is about a single account application. Se você quiser criar um aplicativo de várias contas, precisará definir a lógica para identificar qual conta usar em solicitações de token usando applicationContext.account(forHomeAccountId: self.homeAccountId)If you want to build a multi-account app you'll need to define logic to identify which account to use for token requests using applicationContext.account(forHomeAccountId: self.homeAccountId)

Próximas etapasNext steps

Experimente o tutorial do iOS para obter um guia passo a passo completo sobre a criação de aplicativos, incluindo uma explicação completa sobre este Início Rápido.Try out the iOS tutorial for a complete step-by-step guide on building applications, including a complete explanation of this quickstart.

Saiba como criar o aplicativo usado neste início rápidoLearn how to create the application used in this quickstart

Ajuda e suporteHelp and support

Se você precisar de Ajuda, quiser relatar um problema ou aprender mais sobre as opções de suporte, consulte o seguinte artigo:If you need help, want to report an issue, or want to learn more about your support options, see the following article:

Ajude-nos a melhorar a plataforma de identidade da Microsoft.Help us improve the Microsoft identity platform. Deixe sua opinião respondendo a uma breve pesquisa de duas perguntas.Tell us what you think by completing a short two-question survey.