Azure AD App Only Authentication in SharePoint Online Using PnP PowerShell

Introduction

Azure AD App-only authentication is being used for authenticating to M365 services and doing some operations like read the data, upload the data, or doing some backend jobs via automation scripts. Microsoft encourages you 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 a user’s identity.

In this article, I want to discuss the use case that I came across recently. Previously, I used SharePoint App Only authentication, which is the concept from ACS (Azure Control services) where the Site Collection 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 a 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 IDs and secrets, which becomes cumbersome to deal with.

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

The good news is that in the Azure AD App, the API permissions for SharePoint have come with new permissions called “Sites.Selected”, which will allow your Azure AD App to authenticate to multiple site collections 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 two 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 needed to be deployed between users and Azure AD. CBA with ADFS uses X.509 certificates to authenticate against Azure AD.

• Here, user sign into the application with their credentials and also with a 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, the latest PnP Powershell version must be installed.

Step 1. Open the PowerShell ISE or command windows as an 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 get 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 a certificate and thumbprint. Follow the prompts again.

Step 5. Now you will have the consent pop-up on successful authentication similar to the one 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 ‘App Info’.

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

You will have the following values,

• Pfx file: it includes both public and private key information associated with the certificated. This should not be shared outside your organization.
• Cer file: it has a 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 a certificate used to authenticate the application.
• Base64Encoded: This is the certificate information in ASCII string format.

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

The above steps confirm that the Azure AD application is created with the 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 the Azure AD App, run the following set of commands.

Step 1. Login to the SharePoint admin URL for your tenant using the 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 for what the PnP Management shell could do.

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

Step 3. Grant permission to the app by running the following command. Please note that there are only two sets of permissions you can grant to the app, which are ‘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 have granted permissions. You should see the content without any issues. 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 in 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 checking your App under ‘Enterprise Applications’.

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

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

Get-PnPSite

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

Get-PnPList

You can run the same commands for any other site collection that 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 an 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 'APPLICATIONID' `
    -DisplayName 'SPSitesSelected' `
    -Site 'https://contosodev.sharepoint.com/sites/CBADemo1' `
    -Permissions Write

Grant-PnPAzureADAppSitePermission -AppId 'APPLICATIONID' `
    -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 "APPLICATIONID" `
    -Thumbprint "CERTTHUMBPRINT" `
    -Tenant "contosodev.onmicrosoft.com"

# Getting 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 another site where access is not granted
Connect-PnPOnline -Url "https://contosodev.sharepoint.com/sites/M365POC" `
    -ClientId "APPLICATIONID" `
    -Thumbprint "CERTTHUMBPRINT" `
    -Tenant "contosodev.onmicrosoft.com"

# Get the site details
Get-PnPSite

# Get list content for the site
Get-PnPList

Conclusion

Thus, in this article, we have learned about

• Azure AD Certificate-Based Authentication and
• the different types of authentication
• using the 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/