The component supports App-Only authentication using the AzureServicePrincipalCert authentication scheme and Azure AD application permissions. This setup enables applications to securely access Microsoft SharePoint data without requiring user credentials, making it ideal for automated tasks, background services, and integrations that need seamless access to SharePoint sites.

Important: The Sites.Selected permission is only supported when using SharePoint Online and the REST schema. This setup is not compatible with on-premises SharePoint deployments or other schemas such as CSOM or SOAP.

Microsoft SharePoint permissions for Azure AD applications vary based on the level of access required. Some permissions, like Sites.FullControl.All, grant broad administrative access across all Microsoft SharePoint sites, while others, like Sites.Selected, provide a more restricted, site-specific approach. The appropriate permission depends on your organization's security requirements and how much control should be given to the application.

The following information walks through configuring the component with an Azure AD App to authenticate using certificate-based App-Only access. While this documentation focuses on using the Sites.Selected permission for granular site access, the same steps can apply to other permissions if broader or different levels of access are needed.

Registering an Azure AD App

To authenticate with Microsoft SharePoint using App-Only permissions, you must first create an Azure AD application in Microsoft Entra ID (formerly Azure AD). An Azure AD application acts as a secure identity that allows external applications—like the component—to interact with Microsoft SharePoint using OAuth authentication. This eliminates the need for storing user credentials and enables secure, certificate-based authentication.

Once the application is registered, it is assigned a Client ID and associated with an Azure Tenant. These values are required later when configuring authentication.

Important: This setup requires two Azure AD applications, the main application that connects to Microsoft SharePoint (App 1) and a temporary Admin App (App 2) which is used to grant the main application access to specific Microsoft SharePoint sites. The Admin App must have Sites.FullControl.All permission. If you don't already have an Admin App, you must create one before continuing to grant site access. If you intend to grant access to all sites using Sites.FullControl.All, you only need one application, as it will have tenant-wide permissions without requiring a second app for site assignment. However, if you are restricting access to specific sites, you must create the Admin App before continuing.

Use the following steps to register an application:

1. Log in to the Azure Portal.
2. In the left-hand navigation pane, navigate to Microsoft Entra ID (formerly Azure Active Directory) > App registrations.
3. Click New Registration.
4. Enter an Application Name.
5. Set Supported Account Types to: Accounts in this organizational directory only.
6. Click Register.
7. (Optional): If you don't already have an Admin App, repeat the steps above to create a second app.

Copy and save these values for later as they are required when configuring your connection properties:

• Application (Client) ID – This uniquely identifies the application and is used as the OAuthJWTIssuer in your connection settings.
• Directory (Tenant) ID – This identifies the tenant where the app is registered and is used as the AzureTenant in your connection settings.

Generating and Uploading a Certificate

To use App-Only authentication with the AzureServicePrincipalCert scheme, you must generate and upload a self-signed certificate to your application. This certificate allows secure authentication and replaces traditional password-based authentication.

Note: If you created an Admin App (App 2) to grant permissions to specific sites, it does not require a certificate. Instead, you must generate a client secret for App 2. You can do this in the Azure Portal by navigating to Certificates & Secrets and creating a new client secret.

Use the following steps to generate and upload a certificate:

1. Run the following script in PowerShell (Run as Administrator):
   

   .\Create-SelfSignedCertificate.ps1 -CommonName "MyCompanyName" -StartDate YYYY-MM-DD -EndDate YYYY-MM-DD

2. Export the public (.CER) and private (.PFX) keys.
3. Return to the Azure Portal and open the application you created in Step 1.
4. Navigate to Certificates & Secrets in the left-hand menu.
5. Click Upload Certificate.
6. Select the .CER file (public key) you exported earlier.
7. Click Add.

Assigning Permissions to the App

By default, newly created applications do not have access to Microsoft SharePoint data. To allow the application to interact with Microsoft SharePoint, you must assign the necessary API permissions. Microsoft provides different levels of permissions for Microsoft SharePoint, ranging from full access to all sites (Sites.FullControl.All) to limited access to specific sites (Sites.Selected). The permission model you choose determines how much control the application has over Microsoft SharePoint data.

The following steps focus on Sites.Selected, a permission that allows administrators to grant access only to specific Microsoft SharePoint sites. Unlike Sites.FullControl.All, which gives the application full access across the entire Microsoft SharePoint tenant, Sites.Selected ensures that the application can only interact with approved sites.

When assigning the Sites.Selected permission in the Azure Portal, you must select it under the SharePoint API, not Microsoft Graph. This is because the component uses the SharePoint REST API for connecting to Microsoft SharePoint, and assigning the permission under the wrong API results in authorization failures.

Use the following steps to assign permissions:

1. Open the application you previously created.
2. Navigate to API Permissions in the left-hand navigation menu.
3. Click Add a Permission.
4. Under What type of permissions does your application require?, choose Application Permissions.
5. In the search bar, type Sites.Selected, then check the box next to it.
6. Click Add permissions.
7. To apply these changes, click Grant admin consent for [Your Tenant Name] and confirm.

Granting SharePoint Site Access

By default, the Sites.Selected permission does not automatically grant access to any Microsoft SharePoint site. You must explicitly assign site permissions to the application using PowerShell. This ensures that the application can only interact with approved sites, maintaining security and control over Microsoft SharePoint data.

Note: The component does not support assigning site permissions via Microsoft Graph API. All site-level permission assignments must be completed using PowerShell with the PnP.PowerShell module.

Before proceeding, ensure you have:

• Two Azure AD applications:
  • App 1 (The SharePoint App) with Sites.Selected permission
  • App 2 (An Admin App) with Sites.FullControl.All permission to grant access
• PowerShell installed with the PnP.PowerShell module
• The SharePoint site URL where you want to grant access

Step 1: Install the PnP PowerShell Module

1. Open PowerShell as an administrator.
2. Run the following command:
   

   Install-Module -Name PnP.PowerShell

3. If prompted, confirm the installation by pressing "Y".

Step 2: Connect to the SharePoint Site

1. Run the following command to connect to your SharePoint site:
   

   Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/yourSite" -Interactive

2. Replace https://yourtenant.sharepoint.com/sites/yourSite with the URL of your target SharePoint site.
3. Authenticate using your credentials.

Step 3: Grant Access to the SharePoint App

1. Run the following command to grant write access to the app:
   

          Grant-PnPAzureADAppSitePermission
         -AppId "{sharepoint_app_client_id}"
         -DisplayName "CData SharePoint App"
         -Site "https://yourtenant.sharepoint.com/sites/yourSite"
         -Permissions Write
       

   Note: If you need to grant read-only access instead of write access, update the -Permissions parameter to -Permissions Read.
2. Replace {sharepoint_app_client_id} with your SharePoint application's Client ID.
3. Replace https://yourtenant.sharepoint.com/sites/yourSite with your SharePoint site URL.
4. Press Enter to execute the command.

Note: After granting the application access to a SharePoint site, it may take some time for the permissions to fully propagate. If you do not have immediate access to the site, wait a few hours and try again.

Configuring Connection Properties

Once you've registered your application, uploaded the certificate, and assigned SharePoint site permissions, configure component by specifying these exact connection properties in your application's connection string. These settings instruct component how to authenticate to your SharePoint site using App-Only authentication with the AzureServicePrincipalCert scheme:

Note: Although the AuthScheme has been updated to AzureServicePrincipalCert, the certificate-related connection properties (OAuthJWTCert, OAuthJWTCertType, and OAuthJWTCertPassword) remain unchanged. These properties are still required to supply the certificate used in the underlying JWT-based authentication flow.

URL=https://{name}.sharepoint.com/sites/{site}/;
SharePointEdition=SharePoint Online;
Schema=REST;
AzureTenant={tenant id};
OAuthJWTIssuer={client id};
AuthScheme=AzureServicePrincipalCert;
OAuthJWTCert={file path to certificate (.PFX)};
OAuthJWTCertType=PFXFile;
OAuthJWTCertPassword={certificate password};

Replace the placeholders with the specific values from your setup:

• URL: The SharePoint site URL that your app was granted access to via the Sites.Selected permission.
• AzureTenant: Your Azure Active Directory tenant ID.
• OAuthJWTIssuer: The Client ID for the Azure AD application. This replaces OAuthClientId for the AzureServicePrincipalCert authentication scheme.
• OAuthJWTCert: The absolute file path to your .PFX certificate file.
• OAuthJWTCertType: Set this explicitly to PFXFile as required. If you're using a binary representation of the certificate instead of a file, convert the certificate to a Base64-encoded blob and set this value to PFXBLOB.
• OAuthJWTCertPassword: Password you assigned to the .PFX certificate when exporting it.