Guia do desenvolvedor do SDK do iOS do Microsoft Tunnel para MAM

O guia do desenvolvedor do SDK do iOS do Microsoft Tunnel para MAM é um recurso para desenvolvedores. Ele ajuda os desenvolvedores a integrar e configurar o SDK em um aplicativo iOS/iPadOS. Para obter uma visão geral do Microsoft Tunnel para MAM, confira Microsoft Tunnel para MAM para iOS/iPadOS - Guia de administração do Intune.

Este guia aborda diferentes partes do processo de integração em seu projeto de aplicativo Xcode, incluindo a instalação das estruturas, a configuração do arquivo, as info.plist configurações de compilação, o compartilhamento de chaves e a implementação dos métodos delegados do SDK.

Esses componentes são essenciais no desenvolvimento de um aplicativo iOS/iPadOS. Os desenvolvedores devem entender como navegar e configurar os componentes do SDK. Se você é novo no desenvolvimento de aplicativos Xcode e iOS/iPadOS, este guia pode ajudar. Ele fornece uma visão geral de onde localizar os diferentes componentes do SDK e como usar esses elementos em seus projetos de aplicativo.

Esse recurso aplica-se a:

  • iOS/iPadOS

O que há no repositório do SDK

O repositório do SDK inclui as estruturas a seguir. Você adicionará essas estruturas ao projeto do aplicativo em uma etapa posterior:

  • crypto.xcframework
  • MCPCommon.xcframework
  • MCPCore.xcframework
  • MCPPluginUnencryptedFile.xcframework
  • MicrosoftTunnelApi.xcframework
  • MSTAPNextPluginSecurityOpenssl.xcframework
  • MSTAPNextPluginSwiftSupport.xcframework
  • MSTAPNextPluginVpnMicrosoftTunnel.xcframework
  • ssl.xcframework

Pré-requisitos

Para usar o SDK do Microsoft Tunnel para MAM iOS, os seguintes pré-requisitos são necessários:

  • Um computador macOS com o Xcode 14.0 ou mais recente instalado

  • Seu aplicativo de linha de negócios (LOB) iOS/iPadOS deve ser direcionado para iOS/iPadOS 14.0 ou mais recente.

  • Há dois SDKs do GitHub que você precisa baixar e integrar ao seu aplicativo iOS no Xcode. Verifique se os seguintes projetos foram compilados com êxito antes de continuar com o SDK do Microsoft Tunnel para MAM iOS:

    1. SDK do aplicativo do Intune para iOS (abre um site do GitHub): instale no mínimo a versão 16.1.1.

    Neste site, revise também os Termos de Licença da Microsoft Arquivo SDK do Aplicativo do Intune para iOS.

    Para seus registros, guarde uma cópia dos termos de licença. Ao baixar e usar o SDK do Microsoft Tunnel para MAM iOS, você concorda com os termos de licença. Se você não aceitar os termos de licença, então não use o software.

    1. Biblioteca de Autenticação da Microsoft (MSAL) (abre um site do GitHub): No mínimo, instale a versão 1.2.3.

  • Instale e configure o SDK do Microsoft Tunnel para MAM iOS (abre um site do GitHub). Este SDK é o foco deste artigo.

    Importante

    O Intune lança regularmente atualizações para o SDK do iOS do Microsoft Tunnel para MAM. Regularmente, marcar o SDK do iOS do Microsoft Tunnel para MAM para obter atualizações. Adicione essas atualizações ao seu ciclo de lançamento de desenvolvimento de software. Certifique-se de que seus aplicativos sejam compatíveis com as atualizações e aprimoramentos de recursos do Microsoft Tunnel Gateway.

Como funciona o SDK do iOS do Microsoft Tunnel para MAM

O SDK do iOS do Tunnel for MAM permite que aplicativos iOS/iPadOS estabeleçam uma conexão VPN "no aplicativo". A conexão VPN só existe dentro do aplicativo.

Para resumir, essas conexões VPN no aplicativo são:

  • Conexões VPN discretas, não no nível do dispositivo
  • Com escopo apenas para a camada de rede do aplicativo

Quando um aplicativo faz uma chamada de rede, o SDK intercepta a chamada de rede e estabelece a conexão VPN. Essa conexão VPN no aplicativo não é mostrada no aplicativo Configurações no dispositivo iOS/iPadOS.

Arquitetura: Tunnel for MAM SDK do iOS

A imagem a seguir descreve o fluxo de um aplicativo gerenciado integrado com sucesso ao SDK do Tunnel para MAM iOS:

Desenho do Gateway do Microsoft Tunnel para MAM na arquitetura iOS/iPadOS no Microsoft Intune.

  1. Após a inicialização inicial do aplicativo, uma conexão é feita usando o SDK do Microsoft Tunnel para MAM para iOS.

  2. O túnel recebe um token de autenticação de dispositivo do Microsoft Entra ID.

    Se o dispositivo tiver entrado em outro aplicativo habilitado para MAM, como o Microsoft Outlook, o Microsoft Edge ou o aplicativo móvel do Microsoft 365, talvez o dispositivo já tenha um token de autenticação do Microsoft Entra. Se um token de autenticação válido já existir, o token existente será usado.

  3. Ocorre uma conexão TCP, que é um handshake TLS entre o token e o servidor de encapsulamento.

  4. Se o UDP estiver habilitado no Gateway do Microsoft Tunnel, será feita uma conexão de canal de dados usando DTLS. Se o UDP estiver desabilitado, o TCP estabelecerá o canal de dados para o gateway de encapsulamento.

    Para obter mais informações, consulte as anotações TCP e UDP na visão geral do Microsoft Tunnel - arquitetura.

  5. Quando o aplicativo móvel faz uma conexão com um recurso corporativo local:

    1. Uma API do Microsoft Tunnel para MAM solicita para se conectar ao recurso da empresa.
    2. Uma solicitação da Web criptografada é criada e enviada ao recurso corporativo.

Tarefas do Xcode

Esta seção lista e descreve as tarefas do Xcode que você deve concluir, incluindo:

  • Adicionar as estruturas e bibliotecas
  • Examine e atualize os seguintes recursos:
    • info.plistde arquivo
    • Configurações de compilação
    • Compartilhamento de chaves
  • Use os exemplos para atualizar o projeto AppDelegate do Xcode e adicionar um arquivo delegado do Microsoft Tunnel

Etapa 1 - Adicionar as estruturas e bibliotecas

As estruturas a seguir incluem as APIs necessárias e os métodos delegados para se comunicar com o Gateway do Microsoft Tunnel do Intune. Ela implementa os recursos VPN do Microsoft Tunnel dentro do aplicativo.

Para habilitar o SDK do iOS do Tunnel for MAM, use as seguintes etapas:

  1. Baixe e extraia o SDK do iOS do Tunnel for MAM para uma pasta em um computador macOS. Essa tarefa também está listada nos Pré-requisitos.

    Copie as nove estruturas a seguir para a pasta de estruturas de projeto do aplicativo Xcode:

    • crypto.xcframework
    • MCPCommon.xcframework
    • MCPCore.xcframework
    • MCPPluginUnencryptedFile.xcframework
    • MicrosoftTunnelApi.xcframework
    • MSTAPNextPluginSecurityOpenssl.xcframework
    • MSTAPNextPluginSwiftSupport.xcframework
    • MSTAPNextPluginVpnMicrosoftTunnel.xcframework
    • ssl.xcframework

  2. No projeto Xcode, selecione seu projeto > de aplicativo Adicionar arquivos. No exemplo a seguir, os arquivos são adicionados a um projeto de aplicativo chamado "Flash Chat":

    Tela que mostra como adicionar arquivos ao projeto do aplicativo no Xcode em um dispositivo macOS.

  3. EmDESTINOS DOPROJETO>, selecioneEstruturas de Incorporação de Fases> de Build. Adicionar (+) todas as nove estruturas:

    Captura de tela que mostra a incorporação de estruturas no Xcode em um dispositivo macOS.

    O exemplo a seguir mostra todas as nove estruturas adicionadas:

    Captura de tela que mostra todas as estruturas do Microsoft Tunnel inseridas no Xcode em um dispositivo macOS.

  4. EmDESTINOS DOPROJETO>, selecione Fases >de BuildVincular binário com bibliotecas. Na lista, apenas a MicrosoftTunnelApi.xcframework estrutura deve ser adicionada. Se outras estruturas estiverem listadas, remova-as usando o sinal de subtração (-):

    Captura de tela que mostra como remover estruturas em Vincular binário com bibliotecas no Xcode em um dispositivo macOS.

Etapa 2 - Atualizar o info.plist arquivo

info.plist No projeto do aplicativo Xcode, confirme as seguintes configurações:

  • ID do pacote: Certifique-se de que a mesma ID do pacote listada no registro do aplicativo Microsoft Entra para o aplicativo móvel iOS seja a mesma ID do pacote em seu projeto de aplicativo:

    Para marcar a ID do pacote:

    1. Vá paraMETAS> DO PROJETO>Geral.

    2. Selecione oidentificador do pacote de identidade:>

      Captura de tela que mostra a seleção de projeto, destinos, geral e identidade para adicionar a ID do pacote no Xcode em um dispositivo macOS.

  • Tipos de URL: EmDESTINOS DOPROJETO>, selecione Informações.

    Em Tipos de URL, confirme se a $(PRODUCT_BUNDLE_IDENTIFIER) variável está presente. Quando você integrou o SDK do Aplicativo do Intune para iOS ao projeto do aplicativo (um pré-requisito necessário), essa variável deve ter sido criada.

    Se a variável não estiver lá, você precisará adicioná-la:

    1. Usando o SDK do Aplicativo do Intune para iOS (um pré-requisito necessário), crie uma info.plist propriedade Array e nomeie-a como Esquemas de URL Consultada.

      Adicione os itens de cadeia de caracteres listados na etapa 5 de Criar o SDK em seu aplicativo móvel. Esta etapa cria os esquemas de URL do SDK do MAM do Intune.

      O exemplo a seguir mostra o info.plist usando Esquemas de URL Consultada:

      Captura de tela que mostra a seleção de valores de projeto, destinos, informações, esquemas de URL consultados no Xcode em um dispositivo macOS.

    2. Adicione a $(PRODUCT_BUNDLE_IDENTIFIER) variável.

      O exemplo a seguir mostra a variável em Tipos de $(PRODUCT_BUNDLE_IDENTIFIER)URL:

      Captura de tela que mostra a seleção de projeto, destinos, informações, tipos de URL no Xcode em um dispositivo macOS.

  • IntuneMAMSettings: confirme se as seguintes configurações MSAL estão definidas com os valores de registro de aplicativo do Microsoft Entra apropriados:

    1. Vá paraINFORMAÇÕES DEMETAS>DO PROJETO>.

    2. Selecione IntuneMAMSettings. Confirme as configurações:

      • ADALAuthority: insira a ID de locatário do Microsoft Entra, como https://login.microsoftonline.com/USE_YOUR_ Directory (tenant) ID.
      • ADALClientId: Insira a ID do cliente do aplicativo.
      • ADALRedirectUri: Enter msauth.$(PRODUCT_BUNDLE_IDENTIFIER):/auth.

    Quando você integrou o SDK do Aplicativo do Intune para iOS ao seu projeto de aplicativo (um pré-requisito necessário), essas configurações deveriam ter sido definidas.

    Se essas configurações não estiverem definidas, você precisará defini-las. Para criar a propriedade Dicionário IntuneMAMSettings e as cadeias de caracteres associadas da Biblioteca de info.plist Autenticação da Microsoft, siga o guia do desenvolvedor do SDK do Aplicativo do Intune para iOS (um pré-requisito necessário) em Definir as configurações da MSAL para o SDK do Aplicativo do Intune.

    O exemplo a seguir mostra esses valores configurados:

    Captura de tela que mostra a seleção de projeto, destinos, informações, IntuneMAMSetting no Xcode em um dispositivo macOS.

Etapa 3 - Desativar o Bitcode

  1. Vá paraMETAS>DO PROJETO>Configurações de compilação.
  2. Selecionar opções> de buildHabilitar Bitcode.
  3. Selecione Não.

Captura de tela que mostra a seleção de projeto, destinos, configurações de build, opções de build e a desabilitação de bitcode no Xcode em um dispositivo macOS.

Etapa 4 - Adicionar compartilhamento de conjunto de chaves

O compartilhamento de conjunto de chaves pode estar presente no projeto do aplicativo. Se ela não estiver lá, adicione-a:

  1. Vá paraALVOS> DO PROJETO>Assinatura & Recursos.
  2. Selecione Compartilhamento de chaves.
  3. Na lista Grupos de Conjunto de Chaves , adicione (+) com.microsoft.workplacejoin.

Captura de tela que mostra a seleção de projeto, destinos, Recursos de & de assinatura, compartilhamento de conjunto de chaves e adição de um grupo de conjunto de chaves no Xcode em um dispositivo macOS.

Etapa 5 – Integrar o SDK ao seu aplicativo

✔️ Use o aplicativo de TunnelMAMTestApp2.xcproject exemplo.

Dependendo do aplicativo LOB e sua implementação/finalidade pretendida, o uso do MicrosoftTunnelApi pode variar. Existem algumas funcionalidades principais que você deve conhecer ao integrar o SDK ao seu aplicativo:

  • Todas as interações com o SDK do iOS do Microsoft Tunnel para MAM são tratadas por meio de um MicrosoftTunnelAPI objeto singleton.
  • O MicrosoftTunnelAPI objeto interage com o aplicativo usando um delegado que implementa uma MicrosoftTunnelDelegate interface. 

Para saber como escrever o delegado do Microsoft Tunnel e como inicializar o MicrosoftTunnelAPI, use os aplicativos de exemplo do SDK do iOS do Microsoft Tunnel para MAM (abre um site do GitHub).

Nos aplicativos de exemplo, o projeto Xcode AppDelegate mostra:

  • Como lidar com retornos de chamada de URL MSAL
  • Como iniciar o processo de registro e inicialização necessário para o Tunnel

Para começar, abra o TunnelMAMTestApp2.xcproject aplicativo de exemplo e examine o AppDelegate & MicrosoftTunnelDelegate no projeto do aplicativo.

Aplicativos de exemplo

✔️ Baixe em Aplicativos de exemplo do SDK do iOS do Microsoft Tunnel para MAM (abre um site do GitHub).

Estes aplicativos de exemplo podem ajudá-lo a começar e abranger diferentes cenários.

Métodos MicrosoftTunnelAPI

Inclui MicrosoftTunnelAPI os seguintes métodos:

  • Initialize – Verifica e define as configurações de VPN, configura o registro e configura a MicrosoftTunnelAPI instância.

  • Connect – Obtém a instância e permite a interceptação do MicrosoftTunnelAPI tráfego de rede. Se a API não for inicializada, um erro será mostrado.

  • Disconnect - Obtém a instância e desativa a MicrosoftTunnelAPI interceptação do tráfego de rede. Se a API não for inicializada, um erro será mostrado.

  • onTokenRequired - Opcional. Se o aplicativo já estiver integrado com a IntuneMAM MSAL ou com a MSAL, você precisará implementar esse onTokenRequired método. Esse método usa a e a IntuneMAMSettings MSAL para obter um token de autenticação válido para se conectar ao Gateway do Microsoft Tunnel.

  • Logging – Existem algumas classes de registro diferentes, indicadas por k. Por exemplo, kLoggingClassConnect cria uma saída de log no console do Xcode. Essas chaves de configuração de log podem ser adicionadas à configuração do delegado. Há alguns exemplos dessas classes de registro em log nos aplicativos de exemplo.

    • kLoggingClassInternal
    • kLoggingClassConnect
    • kLoggingClassPacket
    • kLoggingClassSocket
    • kLoggingClassHttp
    • kLoggingClassIntune
    • kLoggingClassMobileAccess
    • kLoggingSeverityDebug
    • kLoggingSeverityInfo
    • kLoggingSeverityWarn
    • kLoggingSeverityMinor
    • kLoggingSeverityMajor
    • kLoggingSeverityCrit

Aviso

Não use chaves de depuração em aplicativos implantados. As chaves podem registrar e mostrar informações de identificação do usuário e dados de segurança.

Registrar em log em aplicativos LOB iOS/iPadOS

A integração do SDK não habilita automaticamente o registro em log. O desenvolvedor deve adicionar o código apropriado para implementar a estrutura delegada de log e fazer as chamadas de log apropriadas. A implementação específica varia dependendo do SDK e dos requisitos do desenvolvedor.

O desenvolvedor deve:

  • Certifique-se de que eles não incluam nenhum dado pessoal de identificação do cliente ou do usuário final em seu registro. Eles devem estar em conformidade com os regulamentos de privacidade.

  • Consulte e trabalhe com a equipe de privacidade da empresa/organização da organização. A equipe de privacidade pode fornecer orientações sobre os dados apropriados que podem ser registrados e as formas apropriadas de lidar com dados confidenciais.

Aviso

Consulte a documentação de privacidade do SDK do iOS do Microsoft Tunnel para MAM (abre um arquivo PDF no GitHub) para obter orientações específicas sobre registro em log e privacidade de dados.

MAM-Tunnel exemplo de método de representante de log

Captura de tela que mostra um método delegado de log do Microsoft Tunnel de exemplo no Xcode em um dispositivo macOS.

Captura de tela que mostra um exemplo de saída de log do Microsoft Tunnel no Xcode em um dispositivo macOS.

Microsoft Tunnel para Gerenciamento de Aplicativos Móveis Informações de privacidade

Sua privacidade é importante para nós. Examine a seguinte documentação online relacionada à privacidade:

Quando o SDK do iOS do Microsoft Tunnel para MAM se integra a aplicativos móveis, os seguintes dados são coletados quando um desenvolvedor:

  • Habilita o módulo de telemetria do Intune MAM no aplicativo

Os dados coletados podem incluir as seguintes áreas:

  • Versão do SDK do Microsoft Tunnel para MAM
  • Informações de usuário geradas pela Microsoft
    • ID do Dispositivo
  • Informações de hardware e software
    • Marca do dispositivo
    • Modelo do dispositivo
    • Versão do sistema operacional do dispositivo
  • Informações do administrador e da conta
    • ID do locatário do Intune
    • ID do locatário do Microsoft Entra
  • Medição de uso:
    • Inicialização de VPN
    • Eventos de conexão e desconexão VPN
  • Informações do erro
    • Erros relacionados a falha de conexão VPN

Nenhuma informação de identificação do usuário é coletada.

Importante

Como desenvolvedor, ao integrar o SDK, é importante não incluir nenhum dado de identificação do usuário ao usar o código para endereçar e capturar mensagens em seu aplicativo.

Problemas conhecidos

Para problemas mais conhecidos, consulte o guia de administração do Microsoft Tunnel para MAM para iOS/iPadOS - Intune.

Próximas etapas

Microsoft Tunnel para MAM para iOS/iPadOS – Guia de administração do Intune

  • Last updated on