Guia de início rápido: inicie sessão em utilizadores e chame o Microsoft Graph a partir de uma aplicação iOS ou macOS

Artigo
10/24/2023

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

O início rápido aplica-se a aplicações 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 subscrição ativa. Crie uma conta gratuitamente.
XCode 10+
iOS 10+
macOS 10.12+

Como funciona a amostra

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

Registar a sua aplicação de início rápido

Gorjeta

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

Para registar a sua aplicação e adicionar as informações de registo da aplicação à sua solução manualmente, siga os passos a seguir:

Entre no centro de administração do Microsoft Entra como pelo menos um desenvolvedor de aplicativos.
Se você tiver acesso a vários locatários, use o ícone Configurações no menu superior para alternar para o locatário no qual deseja registrar o aplicativo no menu Diretórios + assinaturas.
Navegue até Registros do aplicativo Identity>Applications>.
Selecione Novo registo.
Introduza um Nome para a sua aplicação. Os usuários do seu aplicativo podem ver esse nome e você pode alterá-lo mais tarde.
Selecione Registar.
Em Gerir, selecione Autenticação>Adicionar plataforma>iOS.
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 você usa. Observe que a configuração do iOS também é aplicável a aplicativos macOS.
Selecione Configurar e salvar os detalhes da Configuração do MSAL para mais tarde neste início rápido.
Selecionar Concluído.

Etapa 2: Baixe o projeto de exemplo

Etapa 3: Instalar dependências

Extraia o ficheiro zip.
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: Configurar seu projeto

Se selecionou a Opção 1 acima, pode ignorar estes passos.

Abra o projeto no XCode.
Edite ViewController.swift e substitua a linha que começa com 'let kClientID' pelo seguinte trecho de código. Lembre-se de atualizar o valor para kClientID com o clientID que você salvou quando registrou seu aplicativo anteriormente neste início rápido:
```
let kClientID = "Enter_the_Application_Id_Here"
```
Se você estiver criando um aplicativo para nuvens nacionais do Microsoft Entra, substitua a linha que começa com 'let kGraphEndpoint' e 'let kAuthority' por pontos de extremidade corretos. Para acesso global, use valores padrão:
```
let kGraphEndpoint = "https://graph.microsoft.com/"
let kAuthority = "https://login.microsoftonline.com/common"
```
Outros endpoints 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"
```
Abra as configurações do projeto. Na seção Identidade, insira o Identificador do pacote.
Clique com o botão direito do mouse em Info.plist e selecione Abrir como>código-fonte.

Sob o nó raiz dict, substitua Enter_the_bundle_Id_Here pelo Bundle Id 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>

Crie e execute o aplicativo!

Mais Informações

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

Obtenha o MSAL

MSAL (MSAL.framework) é a biblioteca usada para entrar usuários e solicitar tokens usados para acessar uma API protegida pela plataforma de identidade da Microsoft. Pode adicionar a MSAL à sua aplicação através do seguinte processo:

$ vi Podfile

Adicione o seguinte a este 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 MSAL

Pode adicionar a referência para MSAL, adicionando o código seguinte:

import MSAL

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

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:	Description
`clientId`	O ID de Aplicação da aplicação registada em portal.azure.com
`authority`	A plataforma de identidade da Microsoft. Na maioria dos casos, será `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.

Apenas para iOS, requisitos adicionais de aplicativos

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

Nota

No iOS 13+, se você adotar UISceneDelegate em vez de , coloque esse código no retorno de UIApplicationDelegatechamada (consulte a scene:openURLContexts: documentação da Apple). Se você oferecer suporte a UISceneDelegate e UIApplicationDelegate para compatibilidade com iOS mais antigo, o retorno de chamada MSAL precisará ser colocado em ambos os 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)
}

Finalmente, seu aplicativo deve ter uma LSApplicationQueriesSchemes entrada em seu Info.plist ao lado do CFBundleURLTypes. A amostra vem com isso incluído.

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

A MSAL tem dois métodos que servem para comprar tokens: acquireToken e acquireTokenSilent.

acquireToken: Obtenha 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 solicitado a selecionar sua conta, inserir suas credenciais ou consentir com as permissões do seu aplicativo. Por exemplo,

A primeira vez que os utilizadores iniciam sessão na aplicação
Se um utilizador redefinir a palavra-passe, terá de introduzir as suas credenciais
Quando seu aplicativo está solicitando acesso a um recurso pela primeira vez
Quando MFA ou outras políticas de Acesso Condicional são necessárias

let parameters = MSALInteractiveTokenParameters(scopes: kScopes, webviewParameters: self.webViewParamaters!)
self.applicationContext!.acquireToken(with: parameters) { (result, error) in /* Add your handling logic */}

Em que:	Description
`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 da Web personalizadas (`api://<Application ID>/access_as_user`))

acquireTokenSilent: Obtenha um token de acesso silenciosamente

Os aplicativos não devem exigir que seus usuários entrem sempre que solicitarem 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:	Description
`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 da Web personalizadas (`api://<Application ID>/access_as_user`))
`account`	A conta para a qual um token está sendo solicitado. Este início rápido é sobre um aplicativo de conta única. Se você quiser criar um aplicativo com várias contas, precisará definir a lógica para identificar qual conta usar para solicitações de token usando `accountsFromDeviceForParameters:completionBlock:` e passando o correto `accountIdentifier`

Ajuda e suporte

Se precisar de ajuda, quiser comunicar um problema ou quiser saber mais sobre as suas opções de suporte, consulte Ajuda e suporte para programadores.

Próximos passos

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.

Tutorial: Inicie sessão em utilizadores e chame o Microsoft Graph a partir de uma aplicação iOS ou macOS