Desarrollo de la aplicación

  • Artículo

Importante

Las versiones del SDK del servicio Microsoft Rights Management publicadas antes de marzo de 2020 están en desuso; Las aplicaciones que usan versiones anteriores deben actualizarse para usar la versión de marzo de 2020. Para obtener información completa, consulte el aviso de desuso.

No se planean mejoras adicionales para el SDK del servicio Microsoft Rights Management. Se recomienda encarecidamente la adopción del SDK de Microsoft Information Protection para los servicios de clasificación, etiquetado y protección.

En este ejemplo, va a crear una aplicación de consola sencilla que interactúa con el servicio Azure Information Protection (AIP). Se tomará como entrada la ruta de acceso del documento que se va a proteger y luego se protegerá con una directiva ad-hoc o una plantilla de Azure. A continuación, la aplicación aplicará las directivas correctas de acuerdo con las entradas y se creará un documento con información protegida. El código de ejemplo que se usará es la aplicación Azure IP Test, que se encuentra en Github.

Requisitos previos de la aplicación de ejemplo

  • Sistema operativo: Windows 10, Windows 8, Windows 7, Windows Server 2008, Windows Server 2008 R2 o Windows Server 2012.
  • Lenguaje de programación: C# (.NET Framework 3.0 y versiones posteriores).
  • Entorno de desarrollo: Visual Studio 2015 (y versiones posteriores).

Establecimiento de la configuración de Azure

Para configurar Azure para esta aplicación, es necesario crear un identificador del inquilino, una clave simétrica y un id. de entidad de aplicación.

Configuración del inquilino de Azure AD

Para configurar el entorno de Azure AD para Azure Information Protection, siga las instrucciones de Activación del servicio de protección desde Azure Information Protection.

Una vez activado el servicio, necesitará componentes de PowerShell para los siguientes pasos. Para ello, siga Administración de la protección de Azure Information Protection mediante PowerShell.

Obtención del identificador de inquilino

  • Abra PowerShell como administrador.
  • Importe el módulo de RMS: Import-Module AIPService
  • Conéctese al servicio con las credenciales de usuario asignadas: Connect-AipService –Verbose
  • Asegúrese de que RMS está habilitado: enable-aipservice
  • Para obtener su identificador de inquilino, ejecute: Get-AipServiceConfiguration

Registre el valor de BPOSId (identificador de inquilino). La necesitará en pasos posteriores.

Salida de ejemplo: salida del cmdlet Get-AadrmConfiguration

  • Desconéctese del servicio: Disconnect-AipServiceService

Creación de una entidad de servicio

Siga estos pasos para crear a una entidad de servicio:

Una entidad de servicio son credenciales configuradas globalmente para el control de acceso que permiten a los servicios autenticarse en Microsoft Azure AD y proteger la información mediante Microsoft Azure AD Rights Management.

  • Abra PowerShell como administrador.
  • Importe el módulo Microsoft Azure AD mediante: Import-Module MSOnline
  • Conéctese al servicio en línea con las credenciales de usuario asignadas: Connect-MsolService
  • Cree a una nueva entidad de servicio mediante la ejecución de: New-MsolServicePrincipal
  • Proporcione un nombre para la entidad de servicio

    Registre la clave simétrica y el id. de entidad de la aplicación para usarlos más adelante.

Salida de ejemplo: salida del cmdlet NewMsolServicePrincipal

  • Agregue el id. de entidad de la aplicación, la clave simétrica y el identificador de inquilino al archivo App.config de la aplicación.

Ejemplo App.configarchivo de ejemplo App.config archivo

Resumen de diseño

El siguiente diagrama muestra un flujo de proceso y arquitectura de la aplicación que se va a crear. Los pasos se describen a continuación. resumen de diseño

  1. El usuario:
    • Especifica la ruta de acceso del archivo que se va a proteger.
    • Selecciona una plantilla o crea una directiva ad-hoc.
  2. La aplicación solicita la autenticación con AIP.
  3. AIP confirma la autenticación.
  4. La aplicación solicita plantillas a AIP.
  5. AIP devuelve plantillas predefinidas.
  6. La aplicación busca el archivo especificado con la ubicación indicada.
  7. La aplicación aplica la directiva de protección de AIP al archivo.

Funcionamiento del código

En el ejemplo, Azure IP Test, la solución comienza con el archivo Iprotect.cs. Se trata de una aplicación de consola en C# y, al igual que con cualquier otra aplicación habilitada para AIP, se carga MSIPC.dll para comenzar, como se muestra en el método main().

//Loads MSIPC.dll
SafeNativeMethods.IpcInitialize();
SafeNativeMethods.IpcSetAPIMode(APIMode.Server);

Cargue los parámetros necesarios para conectarse a Azure:

//Loads credentials for the service principal from App.Config
SymmetricKeyCredential symmetricKeyCred = new SymmetricKeyCredential();
symmetricKeyCred.AppPrincipalId = ConfigurationManager.AppSettings["AppPrincipalId"];
symmetricKeyCred.Base64Key = ConfigurationManager.AppSettings["Base64Key"];
symmetricKeyCred.BposTenantId = ConfigurationManager.AppSettings["BposTenantId"];

Cuando proporcione la ruta de acceso del archivo en la aplicación de consola, la aplicación comprueba si el documento ya está cifrado. El método es de la clase SafeFileApiNativeMethods.

var checkEncryptionStatus = SafeFileApiNativeMethods.IpcfIsFileEncrypted(filePath);

Si el documento no está cifrado, se procede a cifrar el documento con la selección proporcionada en el símbolo del sistema.

if (!checkEncryptionStatus.ToString().ToLower().Contains(alreadyEncrypted))
{
  if (method == EncryptionMethod1)
  {
    //Encrypt a file via AIP template
    ProtectWithTemplate(symmetricKeyCred, filePath);

  }
  else if (method == EncryptionMethod2)
  {
    //Encrypt a file using ad-hoc policy
    ProtectWithAdHocPolicy(symmetricKeyCred, filePath);
  }
}

La opción de protección con plantilla pasa a obtener la lista de plantillas del servidor y proporciona al usuario la opción que se seleccionará.

Si no modifica las plantillas obtendrá plantillas predeterminadas de AIP.

public static void ProtectWithTemplate(SymmetricKeyCredential symmetricKeyCredential, string filePath)
{
  // Gets the available templates for this tenant
  Collection<TemplateInfo> templates = SafeNativeMethods.IpcGetTemplateList(null, false, true,
      false, true, null, null, symmetricKeyCredential);

  //Requests tenant template to use for encryption
  Console.WriteLine("Please select the template you would like to use to encrypt the file.");

  //Outputs templates available for selection
  int counter = 0;
  for (int i = 0; i < templates.Count; i++)
  {
    counter++;
    Console.WriteLine(counter + ". " + templates.ElementAt(i).Name + "\n" +
        templates.ElementAt(i).Description);
  }

  //Parses template selection
  string input = Console.ReadLine();
  int templateSelection;
  bool parseResult = Int32.TryParse(input, out templateSelection);

  //Returns error if no template selection is entered
  if (parseResult)
  {
    //Ensures template value entered is valid
    if (0 < templateSelection && templateSelection <= counter)
    {
      templateSelection -= templateSelection;

      // Encrypts the file using the selected template
      TemplateInfo selectedTemplateInfo = templates.ElementAt(templateSelection);

      string encryptedFilePath = SafeFileApiNativeMethods.IpcfEncryptFile(filePath,
          selectedTemplateInfo.TemplateId,
          SafeFileApiNativeMethods.EncryptFlags.IPCF_EF_FLAG_KEY_NO_PERSIST, true, false, true, null,
          symmetricKeyCredential);
    }
  }
}

Si selecciona la directiva ad-hoc, el usuario de la aplicación tiene que proporcionar las direcciones de correo electrónico de las personas que tendrán derechos. En esta sección, la licencia se crea mediante el método IpcCreateLicenseFromScratch() y con la aplicación de la nueva directiva en la plantilla.

if (issuerDisplayName.Trim() != "")
{
  // Gets the available issuers of rights policy templates.
  // The available issuers is a list of RMS servers that this user has already contacted.
  try
  {
    Collection<TemplateIssuer> templateIssuers = SafeNativeMethods.IpcGetTemplateIssuerList(
                                                    null,
                                                    true,
                                                    false,
                                                    false, true, null, symmetricKeyCredential);

    // Creates the policy and associates the chosen user rights with it
    SafeInformationProtectionLicenseHandle handle = SafeNativeMethods.IpcCreateLicenseFromScratch(
                                                        templateIssuers.ElementAt(0));
    SafeNativeMethods.IpcSetLicenseOwner(handle, owner);
    SafeNativeMethods.IpcSetLicenseUserRightsList(handle, userRights);
    SafeNativeMethods.IpcSetLicenseDescriptor(handle, new TemplateInfo(null, CultureInfo.CurrentCulture,
                                                            policyName,
                                                            policyDescription,
                                                            issuerDisplayName,
                                                            false));

    //Encrypts the file using the ad hoc policy
    string encryptedFilePath = SafeFileApiNativeMethods.IpcfEncryptFile(
                                    filePath,
                                    handle,
                                    SafeFileApiNativeMethods.EncryptFlags.IPCF_EF_FLAG_KEY_NO_PERSIST,
                                    true,
                                    false,
                                    true,
                                    null,
                                    symmetricKeyCredential);
    }
}

Ejemplo de interacción del usuario

Después de que todo se ha creado y está en ejecución, las salidas de la aplicación se parecerán a estas:

  1. Se le pedirá que seleccione un método de cifrado. salida de la aplicación: paso 1

  2. Se le pide que proporcione la ruta de acceso al archivo que se va a proteger. salida de la aplicación: paso 2

  3. Se le pide que escriba la dirección de correo electrónico del propietario de la licencia (dicho propietario debe tener privilegios de administrador global en el inquilino de Azure AD). salida de la aplicación: paso 3

  4. Escriba las direcciones de correo electrónico de los usuarios que tendrán derechos de acceso al archivo (deben ir separadas por un espacio). salida de la aplicación: paso 4

  5. En la lista, seleccione los derechos que se concederán a los usuarios autorizados. salida de la aplicación: paso 5

  6. Por último, escriba algunos metadatos de directiva: nombre de directiva, descripción y emisor (inquilino de Azure AD) salida de la aplicación de nombre para mostrar : paso 6