Microsoft Information Protection File SDK - Action Justification for lowering a sensitivity label on a file (C#)

This quickstart addresses handling of a downgrade label operation when the label policy requires justification.Here, we will use IFileHandler interface for changing the labels of a file. For further details consult API reference.

Prerequisiti

Se non è già stato fatto, assicurarsi di completare i prerequisiti seguenti prima di continuare:

• Complete Quickstart: Set/get sensitivity labels(C#) which builds a starter Visual Studio solution to list an organization's sensitivity labels and to set and read sensitivity labels to/from a file. This "How to - Downgrade/Remove a label that needs a justification C#" Quickstart builds on the previous one.
• Optionally: Review File handlers concepts in the MIP SDK concepts.

Add logic to set a lower label to a protected file

Add logic to set a sensitivity label on a file, using the File handler object.

1. Open the Visual Studio solution you created in the previous "Quickstart: Set/get sensitivity labels(C#).

2. Using Solution Explorer, open the .cs file in your project that contains the implementation of the Main() method. Per impostazione predefinita, assume lo stesso nome del progetto che lo contiene, specificato durante la creazione del progetto.

3. Update the <label-id> value from previous quickstart to a sensitivity label which requires justification for lowering. During this quickstart run, we'll set this label first and then try to lower it via code snippets in further steps.

4. Toward the end of the Main() body, below Console.ReadKey() and above application shutdown block (where you left off in the previous Quickstart), insert the following code.

   //Set paths and label ID
   string lowerInput = actualOutputFilePath;
   string lowerActualInput = lowerInput;
   string newLabelId = "<new-label-id>";
   string lowerOutput = "<downgraded-labled-output>";
   string lowerActualOutput = lowerOutput;
   
   //Create a file handler for that file
   var downgradeHandler = Task.Run(async () => await fileEngine.CreateFileHandlerAsync(lowerInput, lowerActualInput, true)).Result;
   
   //Set Labeling Options
   LabelingOptions options = new LabelingOptions()
   {
       AssignmentMethod = AssignmentMethod.Standard
   };
   
   try
   {
       //Try to set new label
       downgradeHandler.SetLabel(fileEngine.GetLabelById(newLabelId), options, new ProtectionSettings());
   }
   
   catch (Microsoft.InformationProtection.Exceptions.JustificationRequiredException)
   {
       //Request justification from user
       Console.Write("Please provide justification for downgrading a label: ");
       string justification = Console.ReadLine();
   
       options.IsDowngradeJustified = true;
       options.JustificationMessage = justification;
   
       //Set new label
       downgradeHandler.SetLabel(fileEngine.GetLabelById(newLabelId), options, new ProtectionSettings());
   }
   
   // Commit changes, save as outputFilePath
   var downgradedResult = Task.Run(async () => await downgradeHandler.CommitAsync(lowerActualOutput)).Result;
   
   // Create a new handler to read the labeled file metadata
   var commitHandler = Task.Run(async () => await fileEngine.CreateFileHandlerAsync(lowerOutput, lowerActualOutput, true)).Result;
   
   // Get the label from output file
   var newContentLabel = commitHandler.Label;
   Console.WriteLine(string.Format("Getting the new label committed to file: {0}", lowerOutput));
   Console.WriteLine(string.Format("File Label: {0} \r\nIsProtected: {1}", newContentLabel.Label.Name, newContentLabel.IsProtectionAppliedFromLabel.ToString()));
   Console.WriteLine("Press a key to continue.");
   Console.ReadKey();
   
   

5. Toward the end of Main() find the application shutdown block created in previous quickstart and add below handler lines to release resources.

   downgradeHandler = null;
   commitHandler = null;
   

6. Sostituire i valori segnaposto nel codice sorgente usando i valori seguenti:

   Placeholder	Valore
   <downgraded-labled-output>	The output file path you want to save modified file to.
   <new-label-id>	A template ID, copied from the console output in the previous Quickstart, for example: bb7ed207-046a-4caf-9826-647cff56b990. Make sure it has lower sensitivity than the previously protected file label.

Compilare e testare l'applicazione

Compilare e testare l'applicazione client.

1. Usare CTRL-SHIFT-B (Compila soluzione) per compilare l'applicazione client. Se non sono presenti errori di compilazione, usare F5 (Avvia debug) per eseguire l'applicazione.

2. Se il progetto viene compilato ed eseguito correttamente, l'applicazione potrebbe richiedere l'autenticazione usando Microsoft Authentication Library (MSAL) ogni volta che l'SDK chiama il AcquireToken() metodo. Se le credenziali memorizzate nella cache esistono già, non verrà richiesto di accedere e visualizzare l'elenco delle etichette, seguite dalle informazioni sull'etichetta applicata e sul file modificato.

  Personal : 73c47c6a-eb00-4a6a-8e19-efaada66dee6
  Public : 73254501-3d5b-4426-979a-657881dfcb1e
  General : da480625-e536-430a-9a9e-028d16a29c59
  Confidential : 569af77e-61ea-4deb-b7e6-79dc73653959
  Highly Confidential : 905845d6-b548-439c-9ce5-73b2e06be157
  Press a key to continue.

  Getting the label committed to file: c:\Test\Test_labeled.docx
  Name: Confidential
  IsProtected: True
  Press any key to continue . . .

  Please provide justification for downgrading a label: Lower label approved.
  Getting the new label committed to file: c:\Test\Test_downgraded.docx
  File Label: General
  IsProtected: False
  Press a key to continue.

Please note, similar approach also applies to DeleteLabel() operation, in case the label being deleted from a file requires a justification as per label policy. DeleteLabel() function throws a JustificationRequiredException exception and IsDowngradeJustified flag should be set to true in exception handling before deleting a label successfully.