Added Get-PnPSensitivityLabel (#2023)

* Added Get-PnPSensitivityLabel

* Added PR reference

* Adding documentation to model

Co-authored-by: = <=>

CHANGELOG.md

@@ -57,6 +57,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `-SharingCapability` parameter to the `New-PnPTenantSite` cmdlet to update the Sharing capabilties of the newly provisioned classic site collection. [#1994](https://github.com/pnp/powershell/pull/1994)
 - Added optional `-IncludeAllLists` to `Get-PnPSiteScriptFromWeb` which will include the JSON definition of all custom lists of the current site in the output [#1987](https://github.com/pnp/powershell/pull/1987)
 - Added `-UpdateChildren` parameter to `Add-PnPFieldToContentType` cmdlet. This allows users to skip pushing the fields to child content types. [#1092](https://github.com/pnp/powershell/pull/1992)
+- Added `Get-PnPSensitivityLabel` cmdlet to retrieve Microsoft Purview sensitivity labels available on the tenant [#2023](https://github.com/pnp/powershell/pull/2023)
 
 ### Changed
 

documentation/Get-PnPSensitivityLabel.md

@@ -0,0 +1,94 @@
+---
+Module Name: PnP.PowerShell
+schema: 2.0.0
+applicable: SharePoint Online
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPSensitivityLabel.html
+external help file: PnP.PowerShell.dll-Help.xml
+title: Get-PnPSensitivityLabel
+---
+
+# Get-PnPSensitivityLabel
+
+## SYNOPSIS
+Gets the Microsoft Purview sensitivity labels that are available within the tenant
+
+## SYNTAX
+
+```powershell
+Get-PnPSensitivityLabel [-Identity <Guid>] [-User <AzureADUserPipeBind>] [-Connection <PnPConnection>] [<CommonParameters>]
+```
+
+## DESCRIPTION
+This cmdlet allows retrieval of the available Microsoft Purview sensitivity labels in the currently connected tenant. You can retrieve all the labels, a specific label or all the labels available to a specific user.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPSensitivityLabel
+```
+
+Returns all the Microsoft Purview sensitivitiy labels that exist on the tenant
+
+### EXAMPLE 2
+```powershell
+Get-PnPSensitivityLabel -User johndoe@tenant.onmicrosoft.com
+```
+
+Returns all Microsoft Purview sensitivitiy labels which are available to the provided user
+
+### EXAMPLE 3
+```powershell
+Get-PnPSensitivityLabel -Identity 47e66706-8627-4979-89f1-fa7afeba2884
+```
+
+Returns a specific Microsoft Purview sensitivitiy label by its id
+
+## PARAMETERS
+
+### -Identity
+The Id of the Microsoft Purview sensitivity label to retrieve
+
+```yaml
+Type: Guid
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -User
+The UPN, Id or instance of an Azure AD user for which you would like to retrieve the Microsoft Purview sensitivity labels available to this user
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Connection
+Optional connection to be used by the cmdlet. Retrieve the value for this parameter by either specifying -ReturnConnection on Connect-PnPOnline or by executing Get-PnPConnection.
+
+```yaml
+Type: PnPConnection
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
+[Microsoft Graph documentation](https://docs.microsoft.com/graph/api/informationprotectionpolicy-list-labels)

src/Commands/Base/BasePSCmdlet.cs

@@ -52,14 +52,20 @@ protected override void ProcessRecord()
             }
             catch (PnP.PowerShell.Commands.Model.Graph.GraphException gex)
             {
+                var errorMessage = gex.Error.Message;
+
                 if (gex.Error.Code == "Authorization_RequestDenied")
                 {
                     if (!string.IsNullOrEmpty(gex.AccessToken))
                     {
                         TokenHandler.ValidateTokenForPermissions(GetType(), gex.AccessToken);
                     }
                 }
-                throw new PSInvalidOperationException(gex.Error.Message);
+                if(string.IsNullOrWhiteSpace(errorMessage) && gex.HttpResponse != null && gex.HttpResponse.StatusCode == System.Net.HttpStatusCode.Forbidden)
+                {
+                    errorMessage = "Access denied. Check for the required permissions.";
+                }
+                throw new PSInvalidOperationException(errorMessage);
             }
         }
 

src/Commands/Model/AzureAD/User.cs

@@ -80,6 +80,8 @@ public class User
         /// <returns>PnP PowerShell Azure Active Directory User object</returns>
         internal static User CreateFrom(PnP.Framework.Graph.Model.User entity)
         {
+            if(entity == null) return null;
+
             var user = new User
             {
                 UserPrincipalName = entity.UserPrincipalName,

src/Commands/Model/Graph/GraphException.cs

@@ -1,7 +1,5 @@
 using System;
 using System.Collections.Generic;
-using System.Net;
-using System.Text;
 
 namespace PnP.PowerShell.Commands.Model.Graph
 {
@@ -10,6 +8,8 @@ public class GraphException : Exception
         public GraphError Error { get; set; }
 
         public string AccessToken { get; set; }
+
+        public System.Net.Http.HttpResponseMessage HttpResponse { get; set; }
     }
 
     public class GraphError
@@ -23,6 +23,5 @@ public class GraphError
         public Dictionary<string, object> AdditionalData { get; set; }
 
         public string ThrowSite { get; set; }
-
     }
 }

src/Commands/Model/Graph/Purview/InformationProtectionLabel.cs

@@ -0,0 +1,59 @@
+using System.Text.Json.Serialization;
+
+namespace PnP.PowerShell.Commands.Model.Graph.Purview
+{
+    /// <summary>
+    /// Describes the information protection label that details how to properly apply a sensitivity label to information. The informationProtectionLabel resource describes the configuration of sensitivity labels that apply to a user or tenant.
+    /// </summary>
+    /// <seealso cref="https://docs.microsoft.com/graph/api/resources/informationprotectionlabel"/>
+    public class InformationProtectionLabel
+    {
+        /// <summary>
+        /// The label ID is a globally unique identifier (GUID)
+        /// </summary>
+        [JsonPropertyName("id")]
+        public string Id { get; set; }
+
+        /// <summary>
+        /// The plaintext name of the label.
+        /// </summary>
+        [JsonPropertyName("name")]
+        public string Name { get; set; }
+
+        /// <summary>
+        /// The admin-defined description for the label.
+        /// </summary>
+        [JsonPropertyName("description")]
+        public string Description { get; set; }
+
+        /// <summary>
+        /// The color that the UI should display for the label, if configured.
+        /// </summary>
+        [JsonPropertyName("color")]
+        public string Color { get; set; }
+
+        /// <summary>
+        /// The sensitivity value of the label, where lower is less sensitive.
+        /// </summary>
+        [JsonPropertyName("sensitivity")]
+        public int Sensitivity { get; set; }
+
+        /// <summary>
+        /// The tooltip that should be displayed for the label in a UI.
+        /// </summary>
+        [JsonPropertyName("tooltip")]
+        public string Tooltip { get; set; }
+
+        /// <summary>
+        /// Indicates whether the label is active or not. Active labels should be hidden or disabled in UI.
+        /// </summary>
+        [JsonPropertyName("isActive")]
+        public bool? IsActive { get; set; }
+
+        /// <summary>
+        /// The parent label associated with a child label. Null if label has no parent.    
+        /// </summary>
+        [JsonPropertyName("parent")]
+        public object Parent { get; set; }
+    }
+}

src/Commands/Purview/GetSensitivityLabel.cs

@@ -0,0 +1,57 @@
+using PnP.PowerShell.Commands.Attributes;
+using PnP.PowerShell.Commands.Base;
+using PnP.PowerShell.Commands.Base.PipeBinds;
+using PnP.PowerShell.Commands.Utilities.REST;
+using System;
+using System.Collections.Generic;
+using System.Management.Automation;
+
+namespace PnP.PowerShell.Commands.PowerPlatform.PowerAutomate
+{
+    [Cmdlet(VerbsCommon.Get, "PnPSensitivityLabel")]
+    [RequiredMinimalApiPermissions("InformationProtectionPolicy.Read.All")]
+    [OutputType(typeof(IEnumerable<Model.Graph.Purview.InformationProtectionLabel>))]
+    [OutputType(typeof(Model.Graph.Purview.InformationProtectionLabel))]
+    public class GetSensitivityLabel : PnPGraphCmdlet
+    {
+        [Parameter(Mandatory = false)]
+        public AzureADUserPipeBind User;
+
+        [Parameter(Mandatory = false)]
+        public Guid Identity;
+
+        protected override void ExecuteCmdlet()
+        {
+            string url;
+            if (ParameterSpecified(nameof(User)))
+            {
+                var user = User.GetUser(AccessToken);
+
+                if(user == null)
+                {
+                    WriteWarning("Provided user not found");
+                    return;
+                }
+
+                url = $"/beta/users/{user.UserPrincipalName}/informationProtection/policy/labels";
+            }
+            else
+            {
+                url = "/beta/informationProtection/policy/labels";
+            }
+
+            if (ParameterSpecified(nameof(Identity)))
+            {
+                url += $"/{Identity}";
+
+                var labels = GraphHelper.GetAsync<Model.Graph.Purview.InformationProtectionLabel>(Connection, url, AccessToken).GetAwaiter().GetResult();
+                WriteObject(labels, false);
+            }
+            else
+            {
+                var labels = GraphHelper.GetResultCollectionAsync<Model.Graph.Purview.InformationProtectionLabel>(Connection, url, AccessToken).GetAwaiter().GetResult();
+                WriteObject(labels, true);
+            }
+        }
+    }
+}

src/Commands/Utilities/REST/GraphHelper.cs

@@ -349,6 +349,8 @@ private static async Task<string> SendMessageAsync(PnPConnection connection, Htt
                 var errorContent = await response.Content.ReadAsStringAsync();
                 var exception = JsonSerializer.Deserialize<GraphException>(errorContent, new JsonSerializerOptions() { IgnoreNullValues = true, PropertyNamingPolicy = JsonNamingPolicy.CamelCase });
                 exception.AccessToken = accessToken;
+                exception.HttpResponse = response;
+
                 throw exception;
             }
         }