Authentication

Setting up Access

PnP PowerShell allows you to authenticate with credentials to your tenant. However, due to changes in the underlying SDKs we require you first to register a Azure AD Application which will allow you to authenticate.

The easiest way to do this by using a built-in cmdlet:

Register-PnPManagementShellAccess

You'll notice that the cmdlet is not called Register-PnPPowerShellAccess. This is because both PnP PowerShell and the CLI for Microsoft 365 make use of this Azure AD application.

Important

You need to run this cmdlet with an identity that has write access to the Azure AD. You are not creating a new application in the sense of something that runs in your Azure AD tenant. You're only adding a registration to your Azure AD, a so called 'consent' for people in your tenant to use that application. The access rights the application requires are delegate only, so you will always have to provide credentials or another way of identifying the user actually using that application.

During execution of the cmdlet you will be talked through the consent flow. This means that a browser window will open, you will be asked to authenticate, and you will be asked to consent to a number of permissions. After this permissions has been granted a new entry will show up if you navigate to Enterprise Applications in your Azure AD. If you want to revoke the consent you can simply remove the entry from the Enterprise Applications.

Setting up access to your own Azure AD App

PnP PowerShell has a cmdlet that allows you to register a new Azure AD App, and optionally generate the certificates for you to use to login with that app.

$result = Register-PnPAzureADApp -ApplicationName "PnP Rocks" -Tenant mytenant.onmicrosoft.com -OutPath c:\mycertificates -DeviceLogin
$result

When you run the cmdlet above you will be asked to navigate to the shown url and enter the code shown. After that a new app will be registerd in the Azure AD (make sure you have the rights to do this), and a certificate will be generated and uploaded to that app. After this a URL will be shown which you have to navigate to to provide consent for this application. By default a limited set of permissions scopes is added, but you can provide the one of the permission parameters (GraphApplicationPermissions, GraphDelegatePermissions, SharePointApplicationPermissions, SharePointDelegatePermissions) to provide your own permission scopes.

It also returns the private key certificate encoded in base64 encoding. As it spans multiple lines, it is recommended to assign the outcome of Register-PnPAzureAdApp to a variable so you have access to this value more easily. The Base64 encoded private key certificate can be used in your Connect-PnPOnline voiding the need to have access to the physical file:

Connect-PnPOnline -Url "https://yourtenant.sharepoint.com" -ClientId [clientid] -Tenant [yourtenant.onmicrosoft.com] -CertificateBase64Encoded [pfx base64 encoded]

The cmdlet will also save both the CER and PFX files to the location specified with the -Outpath parameter. The names of the files will be matching the -ApplicationName parameter, e.g. in the example above the files will be called PnP Rocks.cer and PnP Rocks.pfx. The output of the cmdlet will show the clientid. After all is set up and consent has been provided you can login using:

Connect-PnPOnline -Url "https://yourtenant.sharepoint.com" -ClientId [clientid] -Tenant [yourtenant.onmicrosoft.com] -CertificatePath [certificate.pfx]

Authenticating with Credentials

Enter

Connect-PnPOnline -Url https://contoso.sharepoint.com -Credentials (Get-Credential)

and you will be prompted for credentials. Using this method you're required to have granted the PnP Management Shell multi-tenant application access rights. You can however register your own application using Register-PnPAzureAzureApp and then provide the -ClientId parameter with the client id/app id of your custom application.

Authenticating with pre-stored credentials using the Windows Credential Manager (Windows only)

Add-PnPStoredCredential -Name "yourlabel" -Username youruser@domain.com

You will be prompted to provide a password. After that you can login using:

Connect-PnPOnline -Url https://contoso.sharepoint.com -Credentials "yourlabel"

When you create the stored credentials (with Add-PnPStoredCredential or any other tool) if the Name you give it is the URL for your tenant you can omit the -Credentials parameter with Connect-PnPOnline. Using the example above create your stored credential with this command:

Add-PnPStoredCredential -Name "https://contoso.sharepoint.com" -Username youruser@contoso.com

When connecting to https://contoso.sharepoint.com you can use this command:

Connect-PnPOnline -Url https://contoso.sharepoint.com 

Connect-PnPOnline will look through the Windows Credential Manager for a credential matching the URL. If it finds one it will use it. It will also match that credential with deeper connection URLs like https://contoso.sharepoint.com/sites/IT. You can create additional stored credentials for deeper sites if you routinely connect to them with different credentials. If you want to connect with a different set of credentials you can use the -Credentials parameter to specify them. A stored credential can be used for other URLs, like the Admin site:

Connect-PnPOnline -Url https://contoso-admin.sharepoint.com -Credentials https://contoso.sharepoint.com 

Authenticating with pre-stored credentials using the Secrets Management Module from Microsoft (Multi-Platform)

Install-Module -Name Microsoft.PowerShell.SecretManagement -AllowPrerelease
Install-Module -Name Microsoft.PowerShell.SecretStore -AllowPrerelease
Set-SecretStoreConfiguration
Set-Secret -Name "yourlabel" -Secret (Get-Credential)

This creates a new secret vault on your computer. You will be asked to provide a password to access the vault. If you access the vault you will be prompted for that password. In case you want to want to write automated scripts you will have to turn off this password prompt as follows:

Set-SecretStoreConfiguration -Authentication None

For more information about these cmdlets, check out the github repositories: https://github.com/powershell/secretmanagement and https://github.com/powershell/secretstore.

After you set up the vault and you added a credential

Connect-PnPOnline -Url https://contoso.sharepoint.com -Credentials (Get-Secret -Name "yourlabel")

Authentication in case you have Multi-Factor authentication enabled

Connect-PnPOnline -Url https://contoso.sharepoint.com -Interactive

This will show a popup window which will allow to authenticate and step through the multi-factor authentication flow.

Authentication to GCC or National Cloud environments

In order to authentication to a GCC or a national cloud environment you have to take a few steps. Notice that this will work as of release 1.3.9-nightly or later.

Register your own Azure AD App

You are required to register your own Azure AD App in order to authentication

Register-PnPAzureADApp -ApplicationName "PnP PowerShell" -Tenant [yourtenant].onmicrosoft.com -Interactive -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China] -SharePointDelegatePermissions AllSites.FullControl -SharePointApplicationPermissions Sites.FullControl.All -GraphApplicationPermissions Group.ReadWrite.All -GraphDelegatePermissions Group.ReadWrite.All

The AzureEnvironment parameter only allows one value. Select the correct one that matches your cloud deployment.

The above statement grants a few permission scopes. You might want to add more if you want to. Alternatively, after registering the application, navigate to the Azure AD, locate the app registration, and grant more permissions and consent to them.

Optionally modify the manifest for the app

There is a limitation in the Azure AD for national cloud environments where you cannot select permission scopes for SharePoint Online. In order to add specific SharePoint rights you will have to manually add them to the manifest that you can edit in Azure AD:

Locate the requiredResourceAccess section and add to or modify the existing entries. See the example below (notice, this is an example, do not copy and paste this as is as it will limit the permissions to only AllSites.FullControl):

"requiredResourceAccess": [
{
    "resourceAppId": "00000003-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
		{
			"id": "56680e0d-d2a3-4ae1-80d8-3c4f2100e3d0",
			"type": "Scope"
		}
      ]
}

You can add more permissions by using the following values:

The resourceAppId for SharePoint = "00000003-0000-0ff1-ce00-000000000000"

Permission	Permission type	Id	Type
Sites.FullControl.All	Application	678536fe-1083-478a-9c59-b99265e6b0d3	Role
AllSites.FullControl	Delegate	56680e0d-d2a3-4ae1-80d8-3c4f2100e3d0	Scope

Connect

Connect-PnPOnline -Url [yoursite] -Interactive -ClientId [clientid of the app] -Tenant [yourtenant].onmicrosoft.com -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China]

The AzureEnvironment parameter only allows one value. Select the correct one that matches your cloud deployment.