Tutorial: Preparar seu aplicativo iOS (Swift) para autenticação

Este é o segundo tutorial da série de tutoriais que demonstra como adicionar a Biblioteca de Autenticação da Microsoft (MSAL) para iOS e macOS ao seu aplicativo iOS Swift.

Antes de começar, use o seletor Escolha um tipo de inquilino na parte superior desta página para selecionar o tipo de inquilino. O Microsoft Entra ID fornece duas configurações de inquilino, força de trabalho e externo. Uma configuração de locatário da força de trabalho é para seus funcionários, aplicativos internos e outros recursos organizacionais. Um inquilino externo é para as suas aplicações voltadas para o cliente.

Neste tutorial, você:

Pré-requisitos

• Registre um novo aplicativo Web cliente no centro de administração do Microsoft Entra, configurado para Contas em qualquer diretório organizacional e contas pessoais da Microsoft. Consulte Registar uma candidatura para obter mais detalhes. Registre os seguintes valores na página Visão geral do aplicativo para uso posterior:
  • ID da aplicação (cliente)
  • ID do diretório (inquilino)
• Xcode.
• Projeto iOS (Swift).

Adicionar um URL de redirecionamento de plataforma

Para especificar o tipo de aplicativo para o registro do aplicativo, siga estas etapas:

1. Em Gerir, selecione Autenticação >Adicionar uma plataforma>iOS/macOS.
2. Insira o ID do pacote do seu projeto. Se tiver sido baixado o exemplo de código, o ID do pacote será com.microsoft.identitysample.MSALiOS. Se estiver a criar o seu próprio projeto, selecione o seu projeto no Xcode e abra o separador Geral. O identificador do pacote aparece na seção Identidade.
3. Selecione Configurar e guarde a configuração do MSAL que aparece na página de configuração do MSAL para que possa inseri-la ao configurar a sua aplicação mais tarde.
4. Selecione Concluído.

Adicionar a estrutura MSAL a um aplicativo iOS (Swift)

Escolha uma das seguintes maneiras de instalar a biblioteca MSAL em seu aplicativo:

CacauPods

1. Se você estiver usando CocoaPods, instale MSAL criando primeiro um arquivo vazio chamado podfile na mesma pasta que o arquivo de .xcodeproj do seu projeto. Adicione o seguinte a podfile:

   use_frameworks!
   
   target '<your-target-here>' do
      pod 'MSAL'
   end
   

2. Substitua <your-target-here> pelo nome do seu projeto.

3. Em uma janela do terminal, navegue até a pasta que contém o podfile que você criou e execute pod install para instalar a biblioteca MSAL.

4. Feche o Xcode e abra <your project name>.xcworkspace para recarregar o projeto no Xcode.

Cartago

Se você estiver usando Carthage, instale-MSAL adicionando-o ao seu Cartfile:

github "AzureAD/microsoft-authentication-library-for-objc" "master"

Em uma janela do terminal, no mesmo diretório do Cartfileatualizado, execute o seguinte comando para que Carthage atualize as dependências em seu projeto.

iOS:

carthage update --platform iOS

macOS:

carthage update --platform macOS

Manualmente

Você também pode usar o Submódulo Git ou verificar a versão mais recente para usar como uma estrutura em seu aplicativo.

Adicionar o registo da aplicação

Em seguida, adicionamos o registro do aplicativo ao seu código.

Primeiro, adicione a seguinte instrução import à parte superior do arquivo ViewController.swift e de AppDelegate.swift ou de SceneDelegate.swift:

import MSAL

Em seguida, adicione o seguinte código a ViewController.swift antes de viewDidLoad():

// Update the below to your client ID. The below is for running the demo only
let kClientID = "Your_Application_Id_Here"
let kGraphEndpoint = "https://graph.microsoft.com/" // the Microsoft Graph endpoint
let kAuthority = "https://login.microsoftonline.com/common" // this authority allows a personal Microsoft account and a work or school account in any organization's Azure AD tenant to sign in

let kScopes: [String] = ["user.read"] // request permission to read the profile of the signed-in user

var accessToken = String()
var applicationContext : MSALPublicClientApplication?
var webViewParameters : MSALWebviewParameters?
var currentAccount: MSALAccount?

O único valor que você modifica é o valor atribuído a kClientID para ser o seu ID do Aplicativo . Esse valor faz parte dos dados de Configuração do MSAL que você salvou durante a etapa no início deste tutorial para registrar o aplicativo.

Criar instância do SDK

Para criar instância MSAL em seu projeto, execute estas etapas:

Para a classe ViewController, adicione o método initMSAL:

    func initMSAL() throws {

        guard let authorityURL = URL(string: kAuthority) else {
            self.updateLogging(text: "Unable to create authority URL")
            return
        }

        let authority = try MSALAADAuthority(url: authorityURL)

        let msalConfiguration = MSALPublicClientApplicationConfig(clientId: kClientID, redirectUri: nil, authority: authority)
        self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
        self.initWebViewParams()
    }

Ainda na classe ViewController e após o método initMSAL, adicione o método initWebViewParams:

Código iOS:

func initWebViewParams() {
        self.webViewParameters = MSALWebviewParameters(authPresentationViewController: self)
    }

Código macOS:

func initWebViewParams() {
        self.webViewParameters = MSALWebviewParameters()
    }

Definir configurações do projeto Xcode

Adicione um novo grupo de chaves ao seu projeto Assinatura e Capacidades. O grupo de chaves deve ser com.microsoft.adalcache no iOS e com.microsoft.identity.universalstorage no macOS.

Apenas para iOS, configure esquemas de URL

Nesta etapa, você registrará CFBundleURLSchemes para que o usuário possa ser redirecionado de volta ao aplicativo após entrar. A propósito, LSApplicationQueriesSchemes também permite que seu aplicativo use o Microsoft Authenticator.

No Xcode, abra Info.plist como um arquivo de código-fonte e adicione o seguinte dentro da seção <dict>. Substitua [BUNDLE_ID] pelo valor que você usou anteriormente. Se você baixou o código, o identificador do pacote é com.microsoft.identitysample.MSALiOS. Se estiver a criar o seu próprio projeto, selecione o seu projeto no Xcode e abra o separador Geral. O identificador do pacote aparece na seção Identidade.

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>msauth.[BUNDLE_ID]</string>
        </array>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>msauthv2</string>
    <string>msauthv3</string>
</array>

Apenas para macOS, configure o App Sandbox

1. Vá para as Configurações do Projeto Xcode >guia Capacidades>App Sandbox
2. Marque a caixa de seleção Conexões de Saída (Cliente).

Próximos passos

Este é o segundo tutorial da série de tutoriais que demonstra como adicionar a Biblioteca de Autenticação da Microsoft (MSAL) para iOS e macOS ao seu aplicativo iOS Swift.

Antes de começar, use o seletor Escolha um tipo de inquilino na parte superior desta página para selecionar o tipo de inquilino. O Microsoft Entra ID fornece duas configurações de inquilino, força de trabalho e externo. Uma configuração de locatário da força de trabalho é para seus funcionários, aplicativos internos e outros recursos organizacionais. Um inquilino externo é para as suas aplicações voltadas para o cliente.

Neste tutorial, você;

Pré-requisitos

• Registre um novo aplicativo Web cliente no centro de administração do Microsoft Entra, configurado para Contas em qualquer diretório organizacional e contas pessoais da Microsoft. Consulte Registar uma candidatura para obter mais detalhes. Registre os seguintes valores na página Visão geral do aplicativo para uso posterior:
  • ID da aplicação (cliente)
  • ID do diretório (inquilino)
• Xcode.
• Projeto iOS (Swift).

Adicionar um URL de redirecionamento de plataforma

Para especificar o tipo de aplicativo para o registro do aplicativo, siga estas etapas:

1. Em Gerir, selecione Autenticação >Adicionar uma plataforma>iOS/macOS.
2. Insira o ID do pacote do seu projeto. Se tiver sido baixado o exemplo de código, o ID do pacote será com.microsoft.identitysample.MSALiOS. Se estiver a criar o seu próprio projeto, selecione o seu projeto no Xcode e abra o separador Geral. O identificador do pacote aparece na seção Identidade.
3. Selecione Configurar e guarde a configuração do MSAL que aparece na página de configuração do MSAL para que possa inseri-la ao configurar a sua aplicação mais tarde.
4. Selecione Concluído.

Habilitar o fluxo público de clientes

Para identificar seu aplicativo como um cliente público, siga estas etapas:

1. Em Gerir, selecione Autenticação.

2. Em Configurações avançadas, para Permitir fluxos de clientes públicos, selecione Sim.

3. Selecione Guardar para guardar as alterações.

Adicionar a estrutura MSAL a um aplicativo iOS (Swift)

O SDK de autenticação MSAL é usado para integrar a autenticação em seus aplicativos usando OAuth2 padrão e OpenID Connect. Permite autenticar utilizadores ou aplicações com identidades da Microsoft. Para adicionar o MSAL ao seu projeto iOS (Swift), siga estas etapas:

1. Abra seu projeto iOS no Xcode.
2. Selecione Adicionar dependências de pacote... no menu Ficheiro.
3. Digite https://github.com/AzureAD/microsoft-authentication-library-for-objc como URL do pacote e escolha Adicionar pacote

Atualizar o identificador do pacote

No ecossistema Apple, um Identificador de Pacote é um identificador exclusivo para um aplicativo. Para atualizar o identificador de pacote em seu projeto, execute estas etapas:

1. Abra as configurações do projeto. Na seção Identity, insira o Bundle Identifier.

2. Clique com o botão direito Info.plist e selecione Abrir como>Código-Fonte.

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

Criar instância do SDK

Para criar instância MSAL em seu projeto, execute estas etapas:

1. Importe a biblioteca MSAL para o controlador de exibição adicionando import MSAL na parte superior da classe ViewController.

2. Adicione uma variável de membro applicationContext à sua classe ViewController adicionando o seguinte código imediatamente antes da função viewDidLoad():

   var applicationContext : MSALPublicClientApplication?
   var webViewParameters : MSALWebviewParameters?
   

   O código declara duas variáveis: applicationContext, que armazena uma instância de MSALPublicClientApplication, e webViewParameters, que armazena uma instância de MSALWebviewParameters. MSALPublicClientApplication é uma classe fornecida pelo MSAL para lidar com aplicativos cliente públicos. O MSALWebviewParameters é uma classe fornecida pela MSAL que define parâmetros para configurar a exibição da Web usada durante o processo de autenticação.

3. Adicione o seguinte código à função view viewDidLoad():

    do {
           try self.initMSAL()
       } catch let error {
           self.updateLogging(text: "Unable to create Application Context \(error)")
       }
   

   O código tenta inicializar o MSAL, manipulando quaisquer erros que ocorram durante o processo. Se ocorrer um erro, ele atualiza o log com os detalhes do erro.

4. Adicione o seguinte código que cria a função initMSAL(), inicializando o MSAL:

       func initMSAL() throws {
   
       guard let authorityURL = URL(string: Configuration.kAuthority) else {
           self.updateLogging(text: "Unable to create authority URL")
           return
       }
   
       let authority = try MSALCIAMAuthority(url: authorityURL)
   
       let msalConfiguration = MSALPublicClientApplicationConfig(clientId: Configuration.kClientID,
                                                                 redirectUri: Configuration.kRedirectUri,
                                                                 authority: authority)
       self.applicationContext = try MSALPublicClientApplication(configuration: msalConfiguration)
   }
   

   Este código inicializa o MSAL para iOS. Primeiro, tenta criar uma URL para a autoridade usando a cadeia de caracteres Configuration.kAuthority fornecida. Se for bem-sucedido, ele criará um objeto de autoridade MSAL com base nessa URL. Em seguida, ele configura o MSALPublicClientApplication com o ID do cliente, o URI de redirecionamento e a autoridade fornecidos. Se todas as configurações estiverem configuradas corretamente, ele inicializa o contexto do aplicativo com o MSALPublicClientApplicationconfigurado . Se ocorrer algum erro durante o processo, ele lança um erro.

5. Crie o ficheiro Configuration.swift e adicione as seguintes configurações:

   import Foundation
   
   @objcMembers
   class Configuration {
       static let kTenantSubdomain = "Enter_the_Tenant_Subdomain_Here"
   
       // Update the below to your client ID you received in the portal.
       static let kClientID = "Enter_the_Application_Id_Here"
       static let kRedirectUri = "Enter_the_Redirect_URI_Here"
       static let kProtectedAPIEndpoint = "Enter_the_Protected_API_Full_URL_Here"
       static let kScopes = ["Enter_the_Protected_API_Scopes_Here"]
   
       static let kAuthority = "https://\(kTenantSubdomain).ciamlogin.com"
   
   }
   

   Este código de configuração Swift define uma classe chamada Configuration e está marcado com @objcMembers. Ele inclui constantes estáticas para vários parâmetros de configuração relacionados a uma configuração de autenticação. Esses parâmetros incluem o subdomínio inquilino, ID do cliente, URI de redirecionamento, ponto de extremidade protegido da API, e âmbitos. Essas constantes de configuração devem ser atualizadas com valores apropriados específicos para a configuração do aplicativo.

   Encontre o espaço reservado:

   • Enter_the_Application_Id_Here e substitua-o pelo ID do Aplicativo (cliente) do aplicativo que você registrou anteriormente.
   • Enter_the_Redirect_URI_Here e substitua-o pelo valor de kRedirectUri no arquivo de configuração MSAL que você baixou anteriormente quando adicionou a URL de redirecionamento da plataforma.
   • Enter_the_Protected_API_Scopes_Here e substitua-o pelos âmbitos registados anteriormente. Se você não registrou nenhum escopo, pode deixar essa lista de escopo vazia.
   • Enter_the_Tenant_Subdomain_Here e substitua-o pelo subdomínio Directory (locatário). Por exemplo, se o domínio principal do inquilino for contoso.onmicrosoft.com, use contoso. Se não souber o subdomínio do seu locatário, descubra como ler os detalhes do locatário.

Usar domínio de URL personalizado (opcional)

Use um domínio personalizado para marcar totalmente a URL de autenticação. Do ponto de vista do usuário, os usuários permanecem no seu domínio durante o processo de autenticação, em vez de serem redirecionados para ciamlogin.com nome de domínio.

Use as seguintes etapas para usar um domínio personalizado:

1. Use as etapas em Habilitar domínios de URL personalizados para aplicativos em locatários externos para habilitar domínios de URL personalizados para o seu locatário externo.

2. Abra o arquivo Configuration.swift:

   1. Atualize o valor da propriedade kAuthority para https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here. Substitua Enter_the_Custom_Domain_Here pelo seu domínio de URL personalizado e Enter_the_Tenant_ID_Here pelo seu ID de inquilino. Se não tiver o seu ID de arrendatário, saiba como consultar os detalhes do seu arrendatário.

Depois de fazer as alterações no ficheiro Configuration.swift do, se o domínio de URL personalizado for login.contoso.come o ID do locatário for aaaabbbb-0000-cccc-1111-dddd2222eeee, o ficheiro deverá ser semelhante ao seguinte trecho:

    import Foundation

    @objcMembers
    class Configuration {
        static let kTenantSubdomain = "login.contoso.com"
        
        // Update the below to your client ID you received in the portal.
        static let kClientID = "Enter_the_Application_Id_Here"
        static let kRedirectUri = "Enter_the_Redirect_URI_Here"
        static let kProtectedAPIEndpoint = "Enter_the_Protected_API_Full_URL_Here"
        static let kScopes = ["Enter_the_Protected_API_Scopes_Here"]
        
        static let kAuthority = "https://\(kTenantSubdomain)/aaaabbbb-0000-cccc-1111-dddd2222eeee"
    
    }

Próximos passos