Início rápido: inicialização do aplicativo cliente (C#)
Esse início rápido mostra como implementar o padrão de inicialização do cliente, usado pelo wrapper .NET do SDK da PIM em tempo de execução.
Observação
As etapas descritas neste início rápido são necessárias para todos os aplicativos clientes que usam SDKs de Proteção, de Política ou de Arquivos de wrapper .NET da PIM. Embora esse guia de início rápido demonstre o uso dos SDKs de Arquivo, esse mesmo padrão é aplicável aos clientes que usam os SDKs de Política e de Proteção. Os próximos inícios rápidos devem ser realizados em ordem, pois cada um deles se baseia no anterior e este é o primeiro. Esse código destina-se a demonstrar como começar a usar o SDK da PIM e não se destina ao uso para produção.
Pré-requisitos
Caso ainda não tenha feito, faça o seguinte:
- Conclua as etapas em Instalação e configuração do SDK da PIM (Proteção de Informações da Microsoft). Este início rápido "Inicialização do aplicativo cliente" se baseia na instalação e configuração adequadas do SDK.
- Se desejar:
- Examine o Perfil e os objetos do mecanismo. O perfil e os objetos do mecanismo são conceitos universais, exigidos por clientes que usam os SDKs de Arquivo, Políticas e Proteção da PIM.
- Examine os Conceitos de autenticação para saber como a autenticação e o consentimento são implementados pelo aplicativo cliente e o SDK.
Criar uma solução e um projeto do Visual Studio
Primeiro, criamos e configuramos a solução e o projeto iniciais do Visual Studio, nos quais os outros inícios rápidos serão baseados.
Abra o Visual Studio 2019, selecione o menu Arquivo, Novo, Projeto. Na caixa de diálogo Novo Projeto:
No painel esquerdo, em Instalado, Visual C#, selecione Área de Trabalho do Windows.
No painel central, selecione Aplicativo de Console (.NET Framework)
No painel inferior, atualize corretamente o Nome e a Localização do projeto e o Nome da solução que o contém.
Ao terminar, clique no botão OK, no canto inferior direito.
Adicione o pacote Nuget do SDK de Arquivos da PIM ao seu projeto:
- No Gerenciador de Soluções, clique com o botão direito do mouse sobre o nó do projeto (logo abaixo do nó superior/da solução) e selecione Gerenciar pacotes NuGet...:
- Quando a guia Gerenciador de Pacotes NuGet for aberta na área de guias do Grupo do Editor:
- Selecione Procurar.
- Insira "Microsoft.InformationProtection" na caixa de pesquisa.
- Selecione o pacote "Microsoft.InformationProtection.File".
- Clique em "Instalar", depois clique em "OK" quando a caixa de diálogo de confirmação Visualizar alterações for exibida.
Repita as etapas acima para adicionar o pacote do SDK de Arquivo da PIM, mas adicione "Microsoft.Identity.Client" ao aplicativo.
Implementar um representante de autenticação
O SDK da PIM implementa a autenticação usando a extensibilidade de classe, que oferece um mecanismo para compartilhar o trabalho de autenticação com o aplicativo cliente. O cliente precisa adquirir um token de acesso OAuth2 adequado e fornecê-lo ao SDK da PIM no runtime.
Agora, crie uma implementação para um representante de autenticação estendendo a interface Microsoft.InformationProtection.IAuthDelegate
do SDK e substituindo/implementando a função virtual IAuthDelegate.AcquireToken()
. O representante de autenticação é instanciado e usado mais tarde pelos objetos FileProfile
e FileEngine
.
Clique com o botão direito do mouse no nome do projeto no Visual Studio, selecione Adicionar e, em seguida, Classe.
Insira "AuthDelegateImplementation" no campo Nome. Clique em Adicionar.
Adicione usando instruções para a MSAL (Biblioteca de Autenticação da Microsoft) e a biblioteca MIP:
using Microsoft.InformationProtection; using Microsoft.Identity.Client;
Defina
AuthDelegateImplementation
para herdarMicrosoft.InformationProtection.IAuthDelegate
e implementar uma variável privada deMicrosoft.InformationProtection.ApplicationInfo
e um construtor que aceite o mesmo tipo.public class AuthDelegateImplementation : IAuthDelegate { private ApplicationInfo _appInfo; // Microsoft Authentication Library IPublicClientApplication private IPublicClientApplication _app; public AuthDelegateImplementation(ApplicationInfo appInfo) { _appInfo = appInfo; } }
O objeto
ApplicationInfo
contém três propriedades._appInfo.ApplicationId
será usado na classeAuthDelegateImplementation
para fornecer a ID do cliente à biblioteca de autenticação.ApplicationName
eApplicationVersion
serão exibidos nos Relatórios de análise da Proteção de Informações do Azure.Adicione o método
public string AcquireToken()
. Esse método deve aceitarMicrosoft.InformationProtection.Identity
e três cadeias de caracteres: URL de autoridade, URI de recurso e declarações, se necessário. Essas variáveis de cadeia de caracteres serão passadas para a biblioteca de autenticação pela API e não devem ser manipuladas. Insira o GUID do locatário do portal do Azure para seu locatário. A edição de cadeia de caracteres diferentes do GUID do locatário pode resultar em falha na autenticação.public string AcquireToken(Identity identity, string authority, string resource, string claims) { var authorityUri = new Uri(authority); authority = String.Format("https://{0}/{1}", authorityUri.Host, "<Tenant-GUID>"); _app = PublicClientApplicationBuilder.Create(_appInfo.ApplicationId).WithAuthority(authority).WithDefaultRedirectUri().Build(); var accounts = (_app.GetAccountsAsync()).GetAwaiter().GetResult(); // Append .default to the resource passed in to AcquireToken(). string[] scopes = new string[] { resource[resource.Length - 1].Equals('/') ? $"{resource}.default" : $"{resource}/.default" }; var result = _app.AcquireTokenInteractive(scopes).WithAccount(accounts.FirstOrDefault()).WithPrompt(Prompt.SelectAccount) .ExecuteAsync().ConfigureAwait(false).GetAwaiter().GetResult(); return result.AccessToken; }
Implementar um representante de consentimento
Agora crie uma implementação para um representante de consentimento estendendo a interface Microsoft.InformationProtection.IConsentDelegate
do SDK e substituindo/implementando GetUserConsent()
. Uma instância do representante de consentimento é criada e será usada mais tarde pelos objetos Perfil de arquivo e Mecanismo de arquivo. O representante de consentimento recebe o endereço do serviço para o qual o usuário deve dar consentimento usando o parâmetro url
. O representante geralmente deve fornecer algum fluxo que permita que o usuário aceite ou rejeite o consentimento para acesso ao serviço. Para este início rápido embutido em código Consent.Accept
.
Usando o mesmo recurso "Adicionar Classe" do Visual Studio usado anteriormente, adicione outra classe ao seu projeto. Dessa vez, insira "ConsentDelegateImplementation" no campo Nome da Classe.
Agora, atualize ConsentDelegateImpl.cs para implementar sua nova classe representante de consentimento. Adicione a instrução using para
Microsoft.InformationProtection
e defina a classe para herdarIConsentDelegate
.class ConsentDelegateImplementation : IConsentDelegate { public Consent GetUserConsent(string url) { return Consent.Accept; } }
Opcionalmente, tente compilar a solução para garantir que ela seja compilada sem erros.
Inicializar o wrapper gerenciado do SDK da PIM
No Gerenciador de Soluções, abra o arquivo .cs no projeto que contém a implementação do método
Main()
. Ele usa como padrão o mesmo nome que o projeto em que está contido, que você especificou durante a criação do projeto.Remova a implementação gerada de
main()
.O wrapper gerenciado inclui uma classe estática,
Microsoft.InformationProtection.MIP
, usada para inicialização, criando umMipContext
, carregando perfis e liberando recursos. Para inicializar o wrapper para operações no SDK de Arquivo, chameMIP.Initialize()
, passandoMipComponent.File
para carregar as bibliotecas necessárias para as operações com arquivos.Em
Main()
em Program.cs, adicione o seguinte, substituindo <application-id> pela ID do Registro de Aplicativo do Microsoft Entra criado anteriormente.
using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.Exceptions;
using Microsoft.InformationProtection.File;
using Microsoft.InformationProtection.Protection;
namespace mip_sdk_dotnet_quickstart
{
class Program
{
private const string clientId = "<application-id>";
private const string appName = "<friendly-name>";
static void Main(string[] args)
{
//Initialize Wrapper for File SDK operations
MIP.Initialize(MipComponent.File);
}
}
}
Construir um Mecanismo e um Perfil de Arquivo
Como já foi mencionado, os objetos Perfil e Mecanismo são necessários para os clientes do SDK que usam as APIs da PIM. Conclua a parte de codificação deste início rápido, adicionando código para carregar as DLLs nativas e então instanciar os objetos Perfil e Mecanismo.
using System;
using System.Threading.Tasks;
using Microsoft.InformationProtection;
using Microsoft.InformationProtection.File;
namespace mip_sdk_dotnet_quickstart
{
class Program
{
private const string clientId = "<application-id>";
private const string appName = "<friendly-name>";
static void Main(string[] args)
{
// Initialize Wrapper for File SDK operations.
MIP.Initialize(MipComponent.File);
// Create ApplicationInfo, setting the clientID from Microsoft Entra App Registration as the ApplicationId.
ApplicationInfo appInfo = new ApplicationInfo()
{
ApplicationId = clientId,
ApplicationName = appName,
ApplicationVersion = "1.0.0"
};
// Instantiate the AuthDelegateImpl object, passing in AppInfo.
AuthDelegateImplementation authDelegate = new AuthDelegateImplementation(appInfo);
// Create MipConfiguration Object
MipConfiguration mipConfiguration = new MipConfiguration(appInfo, "mip_data", LogLevel.Trace, false);
// Create MipContext using Configuration
MipContext mipContext = MIP.CreateMipContext(mipConfiguration);
// Initialize and instantiate the File Profile.
// Create the FileProfileSettings object.
// Initialize file profile settings to create/use local state.
var profileSettings = new FileProfileSettings(mipContext,
CacheStorageType.OnDiskEncrypted,
new ConsentDelegateImplementation());
// Load the Profile async and wait for the result.
var fileProfile = Task.Run(async () => await MIP.LoadFileProfileAsync(profileSettings)).Result;
// Create a FileEngineSettings object, then use that to add an engine to the profile.
// This pattern sets the engine ID to user1@tenant.com, then sets the identity used to create the engine.
var engineSettings = new FileEngineSettings("user1@tenant.com", authDelegate, "", "en-US");
engineSettings.Identity = new Identity("user1@tenant.com");
var fileEngine = Task.Run(async () => await fileProfile.AddEngineAsync(engineSettings)).Result;
// Application Shutdown
// handler = null; // This will be used in later quick starts.
fileEngine = null;
fileProfile = null;
mipContext.ShutDown();
mipContext = null;
}
}
}
Substitua os valores de espaço reservado no código-fonte que você colou, usando os seguintes valores:
Espaço reservado Valor Exemplo <application-id> ID de Aplicativo do Microsoft Entra atribuída ao aplicativo registrado na "Instalação e configuração do SDK da PIM" (2 instâncias). 0edbblll-8773-44de-b87c-b8c6276d41eb <friendly-name> Um nome amigável definido pelo usuário para o seu aplicativo. AppInitialization <Tenant-GUID> ID do seu locatário do Microsoft Entra TenantID Agora, faça uma compilação final do aplicativo e resolva todos os erros. Seu código deve ser compilado com sucesso.
Próximas etapas
Agora que o seu código de inicialização está completo, você está pronto para o próximo início rápido, onde começará a experimentar os SDKs de arquivo da PIM.