Register an Entra ID Application to use with PnP PowerShell

Note

It has always been a recommended practise to register your own Entra ID Application to use with PnP PowerShell. As of September 9^th, 2024, this has become mandatory step. This article will guide you through how to do so.

The first decision you will have to make is whether you are going to interactively log on through PnP PowerShell to your tenant by providing your credentials, Interactive Login, or if you are aiming to write a script that will log on without requiring any user intervention, App Only Access. Depending on your scenario, continue reading in the appropriate section below.

In this scenario, you will be creating an application registration in Entra ID which will allow you to interactively log on to your tenant using PnP PowerShell. This means that each time you use PnP PowerShell, you will need to enter your credentials and comply with any multi factor authentication and conditional access policies that may have been set up on your tenant.

There are two methods to create your application registration for this scenario: creating it automatically (easiest) or creating it manually. Both will require you to have at least the Application Developer permission role or the Global Administrator permission role. The first should be enough to create the application registration in Entra ID, whenever this has been disabled for normal users, but Global Administrator permissions might be needed after this to set the desired permissions on the application registration. See determining which permissions you need for more information.

Proceed in the section below which matches with your desired option for creating the application registration, automatically or manually.

PnP PowerShell has a cmdlet that allows you to register a new Entra ID Application specifically for interactive login. Notice that you need to be able to create App registrations in your Entra ID.

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP Rocks" -Tenant [yourtenant].onmicrosoft.com -Interactive

When you run the cmdlet above you will be asked to authenticate with your username, password and an optional second factor. After that a new app will be registered in the Entra ID (make sure you have the rights to do this). 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.

After the app has been registered you will be asked to provide consent for the application. Alternatively you can ask someone with the appropriate access rights to navigate to the app registration in the Entra ID portal to add them for you. See determining which permissions you need for more information.

Another option is to manually create the application registration in Entra ID. While the automatic method above is by far the easiest and quickest, for those that like to fully understand each step of the process, can follow this steps in this paragraph in order to create it manually.

Navigate to the Entra ID portal and authenticate with an account that has permissions to create application registrations
Using the menu on the left, go to Identity > Applications > App registrations
At the top, click on New registration
In the Name field, enter any name you would like which indicates to you what the purpose of this script is. Leave the rest of the fields as they are and click on Register at the bottom of the page.
Take note of the Application (client) ID value, as you will use this to connect to PnP PowerShell using the application registration you have just created
In the menu, look for Manage and click on Authentication
Under Platform configurations on the page, click on Add a platform
In the panel that shows up on the right, click on Mobile and desktop applications
Leave the three boxes shown in the panel on the right unchecked and in the Custom redirect URIs field, enter:

http://localhost

Note that this should really be http and not https

Click on Configure at the bottom
Under Manage go to API permissions
In the Configured permissions section, click on the three dots in the line that reads Microsoft Graph (1) and click on Remove all permissions and click on Yes, remove in the confirmation dialog that will show up.
In the Configured permissions section, click on Add a permission
In the panel on the right, stay in the Microsoft APIs category and scroll down to SharePoint and click on it
Click on Delegated permissions
Expand AllSites and check the box for AllSites.Read or any other permission you wish to use with your application registration and click on Add permissions at the bottom
Under Configured permissions click on Grant admin consent for -organization name-

If this button is greyed out, it means you do not have the proper permissions to provide the consent. Log in using an account or ask someone having the Global Administrator role to perform this step for you if this is the case.
In the panel on the right, select No, remove other granted permissions and click on Grant admin consent at the bottom. In the confirmation dialog that appears, click Yes.
The Configured permissions section should now look similar to the screenshot below. You can now use this application to connect to PnP PowerShell or add additional permissions to this application registration as necessary.

Setting up access to your own Entra ID App for App Only Access

If you're looking to register an application in Entra ID to use PnP PowerShell with a script that will run without requiring user interaction, App Only described in this section is what you want to go with.

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

$result = Register-PnPEntraIDApp -ApplicationName "PnP Rocks" -Tenant [yourtenant].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 registered in the Entra ID (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-PnPEntraIDApp 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 [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 [yourtenant].sharepoint.com -ClientId [clientid] -Tenant [yourtenant].onmicrosoft.com -CertificatePath [certificate.pfx]

Special instructions for GCC or National Cloud environments

In order to set up your application registration on a GCC or a national cloud environment, you will have to take a few extra steps. In the two methods described above for interactive login and App Only access, you will have to add -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China] to the cmdlet picking the one that applies to your environment to register your application in Entra ID.

I.e. for an application registration meand for interactive login, use:

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "PnP Rocks" -Tenant [yourtenant].onmicrosoft.com -Interactive -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China]

And for an App Only application registration, use:

$result = Register-PnPEntraIDApp -ApplicationName "PnP Rocks" -Tenant [yourtenant].onmicrosoft.com -OutPath c:\mycertificates -DeviceLogin -AzureEnvironment [USGovernment|USGovernmentHigh|USGovernmentDoD|Germany|China]
$result

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 Entra ID, 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 Entra ID 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 Entra ID:

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

Register an Entra ID Application to use with PnP PowerShell

Note

Setting up access to your own Entra ID App for Interactive Login

Automatically create an app registration for interactive login

Manually create an app registration for interactive login

Setting up access to your own Entra ID App for App Only Access

Special instructions for GCC or National Cloud environments

Optionally modify the manifest for the app