Azure AD App Only Authentication in SharePoint Online using PnP PowerShell

Introduction

Azure AD App only authencitation is being used for authenticating to M365 services and doing some operations like read the data, upload the data or to do some backend jobs via automation scripts.  Microsoft encourages to use certificate-based authentication for your applications registered in Azure AD to authenticate to the M365 or any cloud services. CBA is an extremely robust and secure mechanism for validating user’s identity. 

In this article, I want to discuss about the use case that I came across recently. Previously I am using SharePoint App Only authentication which is the concept from ACS (Azure Control services) where the Site Collection can admin can create Client ID and Client Secret by appending /_layouts/appregnew.aspx in the site collection thus by using the client credentials in application. However, there are few issues using this ACS app-only access token method

• The authentication is not secure. MSFT encourages to switch to Azure AD App only authentication.
• If you want your application to talk to multiple site collections, it is required to create multiple client ID and secrets which becomes cumbersome to deal with.

More about the ACS Token based-authentication can be referred in the references section.

The good news is that in the Azure AD App, the API permissions for the SharePoint have come with new permissions called “Sites.Selected”, which will allow your Azure AD App to authenticate to multiple site collection using single Client and certificate details. 

Before going to this Azure AD App only authentication using certificates, we will try to understand what is Certificate Based Authentication (aka CBA) in Azure AD. There are 2 types of CBA in Azure AD. 

1. Certificate-based authentication with Federated AD FS
2. Azure AD Certificate-based authentication

Certificate-based authentication with Federated AD FS

Previously in order to implement the CBA, ADFS services needs to be deployed between users and Azure AD. CBA with ADFS uses X.509 certificates to authenticate against azure AD.

• Here user signs to application with their credentials and also with certificate installed on their devices.
• ADFS validates the user credentials and certificate and on success passes Access tokens to the user to access the applications.

Azure AD certificate-based authentication

The latest version which is Azure AD CBA doesn’t need configuration and deploying of AD FS. The users can directly interact with Azure AD and authenticate against the applications.

For more details on CBA with AD FS and Azure AD CBA you can go through the articles mentioned in the references section.

Pre-requisites

• PnP.Powershell version 1.10.0. Note that the authentication using CBA is updated in this version.

• PowerShell version 5.1 or later
• The account used to run the PowerShell commands should have ‘Global Admin’ rights.

Create Azure AD App

Now we will go through the steps to create Azure AD App, with API permissions “Sites. Selected” of type “Application”. Then use this Azure AD App to authenticate to multiple site collections.In order to successfully follow the article it is required to have the latest PnP Powershell version installed.

Step 1

Open the PowerShell ISE or command windows as administrator.

Step 2

Register the application by running the below PS command. Make sure the account that is running the below commands should have ‘Global Admin’ rights. Follow the prompts if the account has MFA (Multi-Factor Authentication Enabled)

Register-PnPAzureADApp -ApplicationName SPSitesSelected -Tenant contosodev.onmicrosoft.com -Store CurrentUser -SharePointApplicationPermissions "Sites.Selected" -Interactive

Step 3

On successful authentication, you will be getting the below message which says to wait for 60 seconds to check for required artifacts and start the consent flow.

Step 4

You will be asked to authenticate one more time to register the App and then to create certificate and thumbprint. Follow the prompts again

Step 5

Now you will have the consent pop up on successful authentication similar to below. It shows the App name (In this case it is SPSites Selected), and options to Accept and cancel.

You can also verify the app details by clicking on the ‘App Info’.

Step 6

After agreeing to consent by clicking on ‘Accept’ you should see following information from the command output window.

You will have following values,

• Pfx file: it includes both public and private key information associated to certificated. This should not be shared outside your organization.
• Cer file: it has public key and some information about the device (in this case the server). This is typically exchanged with partners.
• Thumbprint: A secure key associated with certificate used to authenticate to application.
• Base64Encoded: This is the certificate information in ascii string format.

You need to make note of only Client ID, Thumbprint, and the location of the Pfx and Cer files.

The above steps confirms that Azure AD application is created with required permissions which is ‘Sites.Selected’. This means the Azure AD app can be now configured to authenticate to only specific sites.

Granting Access to Azure AD App

Now for granting access to Azure AD App, run the following set of commands.

Step 1

Login to SharePoint admin URL for your tenant using PnP PowerShell Module with Global Admin credentials.

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

Step 2

On authentication you will be getting the following information, about the permissions on what the PnP Management shell could do.

Here you can consent on behalf of organization or leave it unchecked. If you checked ‘Consent on behalf of your organization’ no other user will be prompted for consent.

Step 3

Grant the permission to the app by running the following command. Please note that there is only 2 set of permissions you can grant to app, which is ‘Read’ or ‘Write’.

Grant-PnPAzureADAppSitePermission -AppId 'YOUR APP ID HERE' -DisplayName 'APP DISPLAY NAME HERE' -Site 'https://contosodev.sharepoint.com/sites/CBADemo1' -Permissions Write

Validation

Step 1

Validate the access to the app by connecting to sites that are granted permissions. You should see the content without any issue. In this case, disconnect from the previous PnP connections if there are any previous connections existing.

Disconnect-PnPOnline

Step 2

Validate there is no other PnP connection existing by typing the below command.

Get-PnPConnection

You should see the error says ‘The current connection holds no SharePoint context’.

Step 3

Now connect to the SharePoint site by using Azure AD App credentials.

Connect-PnPOnline -Url "https://contosodev.sharepoint.com/sites/CBADemo2" -ClientId "AZURE AD APP ID" -Thumbprint "CERT THUMP PRINT" -Tenant "YOUR TENANT DOMAIN"

Note that the App ID (Client ID) and Thumbprint values are generated at Step 6 in ‘Create Azure AD App’ section. You can also get the details from your Azure AD by logging into Azure AD Portal and check your App under ‘Enterprise Applications’.

Similarly, the tenant domain can be obtained by clicking on ‘Azure Active Directory’ from quick launch and look for ‘Primary domain’ value.

Step 4

Now check for which site the app is connected to by running below command.

Get-PnPSite

Step 5

Now get the list of all lists in this site collection by running below command.

Get-PnPList

You can run the same commands for any other site collection for which the Azure AD App needs to access.

Step 6

Validate the access to the app by connecting to sites that are not being granted access. You should see 403 forbidden error.

Connect-PnPOnline -Url "https://contosodev.sharepoint.com/sites/M365POC" -ClientId "YOUR CLIENT ID" -Thumbprint "CERT THUMP PRINT" -Tenant "contosodev.onmicrosoft.com"

You might have noticed that it is not throwing any error while connecting to the site using the Client ID and certificate thump print, however it is throwing error when getting the site details or list content.

Complete Script

#Creating Azure AD App with Certificate Thumbprint.
Register-PnPAzureADApp -ApplicationName SPSitesSelected -Tenant contosodev.onmicrosoft.com -Store CurrentUser -SharePointApplicationPermissions "Sites.Selected" -Interactive
#Connecting to SharePoint online Admin center using Global Admin Credentials
Connect-PnPOnline -Url "https://contosodev-admin.sharepoint.com" -Interactive
#Granting Access to Azure AD App for specific sites
Grant-PnPAzureADAppSitePermission -AppId 'bf8f7d56-c37f-44d6-abcb-670832e49b9c' -DisplayName 'SPSitesSelected' -Site 'https://contosodev.sharepoint.com/sites/CBADemo1' -Permissions Write
Grant-PnPAzureADAppSitePermission -AppId 'bf8f7d56-c37f-44d6-abcb-670832e49b9c' -DisplayName 'SPSitesSelected' -Site 'https://contosodev.sharepoint.com/sites/CBADemo2' -Permissions Write
#Disconnecting the previous connections
Disconnect-PnPOnline
#Validating the connection
Get-PnPConnection
#Connecting to SPO site using Azure AD App
Connect-PnPOnline -Url "https://contosodev.sharepoint.com/sites/CBADemo1" -ClientId "bf8f7d56-c37f-44d6-abcb-670832e49b9c" -Thumbprint "6A506565EABCD759C204C8517955301420A0C02D" -Tenant "contosodev.onmicrosoft.com"
#Gettting site details
Get-PnPSite
#Getting the list content
Get-PnPList
#Disconnecting from the Azure AD App connection
Disconnect-PnPOnline
#Connecting to SPO site using Azure Ad App with other site where access is not being granted.
Connect-PnPOnline -Url "https://contosodev.sharepoint.com/sites/M365POC" -ClientId "bf8f7d56-c37f-44d6-abcb-670832e49b9c" -Thumbprint "6A506565EABCD759C204C8517955301420A0C02D" -Tenant "contosodev.onmicrosoft.com"
#Get the site details
Get-PnPSite
#Get list content for site
Get-PnPList

Conclusion

Thus, in this article, we have learned about

• what is Azure AD Certificate Based Authentication and
• the different types of authentication
• using PnP module to generate Azure AD App with ‘Sites.Selected” api permissions.
• Granting access to Azure AD App and then validating the access.

References

• https://docs.microsoft.com/en-us/azure/active-directory/authentication/concept-certificate-based-authentication
• https://4sysops.com/archives/azure-ad-certificate-based-user-authentication/
• https://docs.microsoft.com/en-us/azure/active-directory/authentication/active-directory-certificate-based-authentication-get-started
• https://docs.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs
• https://lazyadmin.nl/powershell/install-azure-ad-module/
• https://www.leonarmston.com/2022/01/pnp-powershell-csom-now-works-with-sharepoint-sites-selected-permission-using-azure-ad-app/