Feat: enhance Linux credential management with secure storage and retrieval (#5429)

* Feat: enhance Linux credential management with secure storage and retrieval

* Fix: fall back to OS credential store when no default vault is registered

Resolve the default vault once in AddCredential, GetCredential and
RemoveCredential and fall through to the OS specific credential store
when it is empty, matching what AddAppId, GetAppId and RemoveAppid
already do. Previously these branched on whether the SecretManagement
module was installed, so a machine with the module installed but no
default vault registered stored nothing while reporting success, and
retrieved and removed nothing.

Document the Linux Secret Service storage and its prerequisites in the
stored credential cmdlet documentation and the credential management
article.

Author: gautamdsheth

CHANGELOG.md

@@ -27,6 +27,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Changed `Export-PnPFlow -AsZipPackage` and `Export-PnPPowerApp` to ask for confirmation before overwriting an existing file when `-OutPath` is omitted, as they already did when `-OutPath` is specified. Unattended scripts that rely on the previous silent overwrite need to specify `-Force`. [#5421](https://github.com/pnp/powershell/pull/5421)
 
 ### Fixed
+- Fixed `Add-PnPStoredCredential`, `Get-PnPStoredCredential` and `Remove-PnPStoredCredential` not working on Linux when `Microsoft.PowerShell.SecretManagement` is not configured. Storing a credential reported success while writing nothing, and retrieving or removing one always came back empty, which also meant `Connect-PnPOnline` never resolved a stored credential on Linux. Credentials are now written to and read from the Linux Secret Service, and the username is stored alongside the password so a complete `PSCredential` is returned rather than the password on its own. Credentials are kept under their own keyring schema, separate from the one holding managed application ids. The same cmdlets were also silently doing nothing when `Microsoft.PowerShell.SecretManagement` is installed without a default vault being registered, on every platform, and now fall back to the credential store of the operating system in that situation. [#5429](https://github.com/pnp/powershell/pull/5429)
 - Fixed the access token permission validation reporting a required permission as missing when the token holds a scope which covers it, such as a token with `Sites.FullControl.All` being reported as lacking `Sites.Read.All`. The permission metadata states the least privileged scope which suffices, so a more privileged scope now satisfies it. This affects the validation message written to the trace log by every cmdlet as well as `Test-PnPConnectionPermission`. [#5428](https://github.com/pnp/powershell/pull/5428)
 - Fixed the documented permissions of `Get-PnPGraphSubscription`, which listed `Subscription.Read.All` as required. That permission is only needed to also return subscriptions created by other applications; reading back a subscription created by the current application requires the same permissions on the subscribed resource that were needed to create it. Also documented the resource dependent permissions of `New-PnPGraphSubscription`, `Set-PnPGraphSubscription`, `Remove-PnPGraphSubscription` and `Invoke-PnPGraphMethod`, and corrected `Set-PnPGraphSubscription` linking to the delete instead of the update API documentation. [#5427](https://github.com/pnp/powershell/pull/5427)
 - Fixed the documented Microsoft Graph permission of `Sync-PnPSharePointUserProfilesFromAzureActiveDirectory`, which listed `User.Read`. Listing all users from Entra ID requires `User.Read.All`, and Microsoft Graph is only called when `-Users` is not provided. Its SharePoint permissions are now declared as metadata as well. [#5427](https://github.com/pnp/powershell/pull/5427)

documentation/Add-PnPStoredCredential.md

@@ -10,7 +10,7 @@ title: Add-PnPStoredCredential
 # Add-PnPStoredCredential
 
 ## SYNOPSIS
-Adds a credential to the Windows Credential Manager or Mac OS Key Chain Entry.
+Adds a credential to a secret vault, the Windows Credential Manager, the macOS Keychain or the Linux Secret Service.
 
 ## SYNTAX
 
@@ -20,7 +20,9 @@ Add-PnPStoredCredential -Name <String> -Username <String> [-Password <SecureStri
 ```
 
 ## DESCRIPTION
-Adds an entry to the Windows Credential Manager or Mac OS Key Chain Entry. If you add an entry in the form of the URL of your tenant/server PnP PowerShell will check if that entry is available when you connect using Connect-PnPOnline. If it finds a matching URL it will use the associated credentials.
+Adds an entry to the credential store of your platform. If a default vault has been registered through `Microsoft.PowerShell.SecretManagement`, the credential is stored in that vault. If not, it is stored in the credential store native to the operating system: the Windows Credential Manager on Windows, the Keychain on macOS and the Secret Service on Linux. Storing a credential on Linux without a default vault requires a Secret Service provider such as GNOME Keyring or KWallet to be installed and unlocked; if none is available, the cmdlet will report that it could not store the credential rather than silently discarding it. See [Credential Management](https://pnp.github.io/powershell/articles/credentialmanagement.html) for the details.
+
+If you add an entry in the form of the URL of your tenant/server PnP PowerShell will check if that entry is available when you connect using Connect-PnPOnline. If it finds a matching URL it will use the associated credentials.
 
 If you add a Credential with a name of "https://yourtenant.sharepoint.com" it will find a match when you connect to "https://yourtenant.sharepoint.com" but also when you connect to "https://yourtenant.sharepoint.com/sites/demo1". Of course you can specify more granular entries, allow you to automatically provide credentials for different URLs.
 
@@ -65,7 +67,7 @@ Accept wildcard characters: False
 ```
 
 ### -Overwrite
-Use parameter to overwrite existing Mac OS Key Chain Entry. Not required on Windows.
+Use parameter to overwrite an existing macOS Keychain entry. Not required on Windows or Linux.
 
 ```yaml
 Type: SwitchParameter

documentation/Get-PnPStoredCredential.md

@@ -19,7 +19,7 @@ Get-PnPStoredCredential -Name <String>
 ```
 
 ## DESCRIPTION
-Returns a stored credential from the Windows Credential Manager or Mac OS Key Chain Entry.
+Returns a stored credential. If a default vault has been registered through `Microsoft.PowerShell.SecretManagement`, the credential is read from that vault. If not, it is read from the credential store native to the operating system: the Windows Credential Manager on Windows, the Keychain on macOS and the Secret Service on Linux. Reading a credential from the Linux Secret Service requires a provider such as GNOME Keyring or KWallet to be installed and unlocked. See [Credential Management](https://pnp.github.io/powershell/articles/credentialmanagement.html) for the details.
 
 ## EXAMPLES
 

documentation/Remove-PnPStoredCredential.md

@@ -10,7 +10,7 @@ online version: https://pnp.github.io/powershell/cmdlets/Remove-PnPStoredCredent
 # Remove-PnPStoredCredential
 
 ## SYNOPSIS
-Removes a credential from the Credential Manager
+Removes a stored credential
 
 ## SYNTAX
 
@@ -19,7 +19,7 @@ Remove-PnPStoredCredential -Name <String> [-Force]
 ```
 
 ## DESCRIPTION
-Removes a stored credential from the Credential Manager
+Removes a stored credential. If a default vault has been registered through `Microsoft.PowerShell.SecretManagement`, the credential is removed from that vault. If not, it is removed from the credential store native to the operating system: the Windows Credential Manager on Windows, the Keychain on macOS and the Secret Service on Linux. See [Credential Management](https://pnp.github.io/powershell/articles/credentialmanagement.html) for the details.
 
 ## EXAMPLES
 
@@ -28,7 +28,7 @@ Removes a stored credential from the Credential Manager
 Remove-PnPStoredCredential -Name "https://tenant.sharepoint.com"
 ```
 
-Removes the specified credential from the Credential Manager
+Removes the specified credential from the credential store
 
 ## PARAMETERS
 

pages/articles/credentialmanagement.md

@@ -4,7 +4,9 @@ PnP PowerShell is the ultimate library to execute cmdlets unattended in scripts,
 
 However, in order to automate authentication you need to safely store these credentials. You should -never- store them in your scripts.
 
-We currently recommend the Microsoft provided Secret Management and Secret Store modules to set up a vault which PnP PowerShell can use to store and retrieve credentials.
+We currently recommend the Microsoft provided Secret Management and Secret Store modules to set up a vault which PnP PowerShell can use to store and retrieve credentials. This works the same way on every platform PnP PowerShell runs on, which is why it is the recommended option.
+
+If you do not register a default vault, `Add-PnPStoredCredential`, `Get-PnPStoredCredential` and `Remove-PnPStoredCredential` fall back to the credential store built into your operating system, described under [Storing credentials without a vault](#storing-credentials-without-a-vault) below.
 
 ## Install the required modules
 
@@ -78,3 +80,17 @@ Remove-Secret -Name [yourlabel] -Vaultname [VaultName]
 ```powershell
 Remove-PnPStoredCredential -Name [yourlabel]
 ```
+
+## Storing credentials without a vault
+
+When no default vault is registered, the PnP PowerShell cmdlets above use the credential store that comes with your operating system. Nothing needs to be installed for this on Windows and macOS, and the credentials are stored under a name prefixed with `PnPPS:`.
+
+| Platform | Credential store | Prerequisites |
+| -------- | ---------------- | ------------- |
+| Windows | Windows Credential Manager | None |
+| macOS | Keychain | None |
+| Linux | Secret Service | A Secret Service provider such as GNOME Keyring or KWallet must be installed, running and unlocked |
+
+On Linux this means a headless machine, a container or an SSH session without a running keyring daemon typically has no Secret Service available. `Add-PnPStoredCredential` will then fail with an error explaining that the credential could not be stored, and `Get-PnPStoredCredential` will return nothing. On such machines, register a default vault with the Secret Management modules as described above, or pass credentials to `Connect-PnPOnline` in another way.
+
+Note that a credential stored in the operating system credential store is not visible to the Secret Management module, and the other way around. If you register a default vault after having stored credentials natively, PnP PowerShell will look in the vault only and you will need to add the credentials there again.

pages/articles/toc.yml

@@ -2,12 +2,18 @@
   items:
     - name: Installation
       href: installation.md
+    - name: Command suggestions while you type (predictor)
+      href: powershellpredictor.md
     - name: Register your application
       href: registerapplication.md
     - name: Determine permissions
-      href: determinepermissions.md      
+      href: determinepermissions.md
     - name: Connecting and authenticating
       href: authentication.md
+    - name: Staying signed in between sessions
+      href: persistedlogin.md
+    - name: Storing credentials securely
+      href: credentialmanagement.md
     - name: Samples
       href: scriptsamples.md
 - name: Configure PnP PowerShell
@@ -46,10 +52,6 @@
       href: batching.md
     - name: Upgrading from the Legacy version
       href: upgrading.md
-    - name: Credential Management
-      href: credentialmanagement.md
-    - name: Working with persisted logins
-      href: persistedlogin.md
     - name: Dealing with the ACS deprecation
       href: acsdeprecation.md
 - name: How to contribute
@@ -69,8 +71,6 @@
     - name: Working with permission attributes
       href: permissionattributes.md
 - name: Useful helper tools
-  items:      
-    - name: PnP PowerShell predictor
-      href: powershellpredictor.md
+  items:
     - name: Visual Studio Code extension
       href: vscodeextension.md