Connect to Sharepoint Online using a Certificate in Azure KeyVault

In this blog post, we will explore how to connect to SharePoint Online using the Connect-PnPOnline PowerShell cmdlet. You can use this approach to establish a connection to SharePoint Online when creating an unattended PowerShell script.

The steps provided in this blog post will enable you to establish a connection to SharePoint Online without encountering any username/password prompts. Instead, we will utilize a self-signed certificate, ClientID, tenantID, and SiteURL for the connection to SharePoint Online.

A self-signed certificate PFX file is used to establish a connection to SharePoint Online. This method allows anyone possessing the certificate and its private key to utilize the app and the permissions granted to the app for connecting to SharePoint Online.

You can store this certificate on your local device or a remote file server and utilize the Connect-PnPOnline cmdlet to establish a connection. However, it is recommended to store the certificate in a secure location with permission controls, such as Azure KeyVault.

Steps to Connect to Sharepoint Online Using a Certificate

  1. Create a Self-Signed certificate.
  2. Create a Service principal/App Registration in Entra ID.
  3. Connect the certificate to the application.
  4. Create an Azure Key Vault.
  5. Import the self-signed certificate into Azure Key Vault.
  6. Provide “Get” and “List” permissions to the Entra ID Service Principal on Azure Key Vault.
  7. Retrieve the self-signed certificate from Azure Key Vault using PowerShell.
  8. Use the Connect-PnPOnline cmdlet to establish a connection to SharePoint Online using PowerShell.

Let’s Explore all the steps:

1. Create a Self-Signed certificate

The first step is to create a self-signed certificate. To do this, follow Step 1 of the blog post “Connect to SharePoint Online Using PowerShell“.

2. Create a Service Principal in Entra ID

Create a service Principal in Entra ID by Navigating to Entra admin center > Applications > App registrations. Follow Step 2 of the blog post Connect To Sharepoint Online Using Powershell to create a service principal.

3. Connect the Certificate to the Application

The next step is to connect the self-signed certificate to the Entra ID Service principal/application registered which we created in Step 2. Follow Step 3 of the blog post “Connect to SharePoint Online Using PowerShell” to complete this connection.

4. Create an Azure KeyVault

Once you have completed Steps 1, 2, and 3, you can now create an Azure KeyVault using the following PowerShell command. Alternatively, you can manually create an Azure KeyVault by logging on to the Azure Portal.

Create Azure KeyVault

New-AzKeyVault -Name "Mytestkeyvault001" -ResourceGroupName "uk-south01" -Location "UK South"

4.1 Import Self-Signed Certificate in Azure KeyVault

The generated self-signed certificate PFX file, along with its password, needs to be imported into Azure KeyVault. To import the certificate into Azure KeyVault, please follow the steps below:

  1. Open Azure KeyVault “Mytestkeyvault001”.
  2. Click on “Certificates“.
  3. Click on “+ Generate/Import“.
Import Self-Signed Certificate in Azure KeyVault
Import Self-Signed Certificate in Azure KeyVault
  • Select the method of Certificate Creation as “Import“.
  • Certificate Name: Provide any user-friendly name for the certificate.
  • Upload Certificate File: Browse to the certificate PFX file.
  • Password: Provide the password for the certificate PFX file.
  • Click on “Create” to initiate the import process.
Import Self-Signed Certificate in Azure KeyVault
Import Self-Signed Certificate in Azure KeyVault

4.2 Assign Get/List Permission to the Service Principal in Azure KeyVault

Once the certificate is imported, we need to provide “Get” and “List” permissions to the Entra ID service principal in Azure KeyVault. Please follow the steps below to grant these permissions:

  • Open Azure KeyVault “Mytestkeyvault001”.
  • Click on “Access policies“.
  • Click on “+ Create“.
Assign Get/List Permission to the Service Principal in Azure KeyVault
Assign Get/List Permission to the Service Principal in Azure KeyVault
  • On the “Permissions” tab:
    • Select “Get” under “Secret permissions“.
    • Select “Get” and “List” under “Certificate permissions“.
Azure keyvault access policy for Sharepoint online service principal
Assign Get/List Permission to the Service Principal in Azure KeyVault
  • On the “Principal” tab, search for the service principal and select it. Click “Next” to proceed. Move to the “Application” and “Review + Create” tabs, then click “Create” to establish the permissions.
Search for sharepoint online service principal in Azure KeyVault Access Policy
Assign Get/List Permission to the Service Principal in Azure KeyVault
  • After creating the application permissions, they will be listed under “Access policies“. You can also review the permissions assigned to the service principal under “Secret Permissions” and “Certificate Permissions“.
Sharepoint service principal Get and List permissions to Azure Keyvault
Assign Get/List Permission to the Service Principal in Azure KeyVault

5. Retrieve Self-Signed Certificate from Azure KeyVault using Powershell

To retrieve the self-signed certificate from Azure KeyVault, you will first need to connect to Azure using the Connect-AzAccount cmdlet, which is part of the Az PowerShell module.

If you do not have the Az PowerShell module installed on your device, you may encounter an error stating that the Connect-AzAccount command is not recognized.

  1. To install the Az PowerShell module, use the following command:

Install the Az Powershell module

Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force
  1. Connect to Azure using Connect-AzAccount
    • $ApplicationId: Provide the ClientID of the Entra ID Registered App with the same certificate and KeyVault permissions configured.
    • $TenantId: Provide the Tenant ID of your organization. You can find the Tenant ID of your organization on the Overview tab of the Entra admin center.
    • $ClientSecret: Provide the Client Secret of the service principal. You can find the Client Secret by navigating to the Entra admin center > Applications > App registrations > Click on the Application > Certificate & secrets > Client secrets.

If you have not created a Client Secret, you can click on the “+ New client secret” button. Provide a description and expiry date for this client secret. Click on “Add” to create a client secret. Make sure to copy the Client Secret Value, not the Secret ID, for the commands/script.

Note

Connect to Azure using Connect-AzAccount

$ApplicationId ="ee15adf9-eabd-4bcf-bbf3-cc0f7d2616ba"
$TenantId= "97659d97-8dab-4122-80bd-caadf41b64d7"
[string][ValidateNotNullOrEmpty()] $ClientSecret = "hLT8Q~8mCkXdGVsMnsdE61IhFskED6m8I5ExJbcI"
$AzPassword = ConvertTo-SecureString -String $ClientSecret -AsPlainText -Force
$Credential = New-Object -TypeName System.Management.Automation.PSCredential -ArgumentList $ApplicationId, $AzPassword
Connect-AzAccount -ServicePrincipal -TenantId $TenantId -Credential $Credential
  1. Use the Get-AzKeyVaultSecret cmdlet to retrieve the certificate in a PowerShell variable.
    • $VaultName: Provide the Azure KeyVault name.
    • $certName: Provide the certificate name as shown in Azure KeyVault.
    • $secretValueText: This variable will store the certificate value.

Retrieve the Certificate in a Powershell variable

# Specify Azure Key Vault Name and Cert Name
$VaultName = "Mytestkeyvault001"
$certName = "SPOConnectPSCert"

# Get the cert stored in KeyVault
$secret = Get-AzKeyVaultSecret -VaultName $vaultName -Name $certName
$secretValue = $secret.SecretValue
$bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($secretValue);
$secretValueText = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr);

6. Use Connect-PnPOnline to Connect to Sharepoint online

The last step is to use the variables $secretValueText, $clientID, $tenant, and $siteurl to connect to SharePoint Online using the Connect-PnPOnline command.

  • $tenant: Provide your organization’s tenant name.
  • $siteurl: Provide the SharePoint Online site URL to connect.
  • $clientID: Provide the ClientID of the Entra ID Registered App with the same certificate and KeyVault permissions configured.

Connect to Sharepoint online

# Connect to PnPOnline
$tenant = "mylab000.onmicrosoft.com" # or tenantId
$siteUrl = "https://mylab000.sharepoint.com/sites/Finance"
$clientID = "ee15adf9-eabd-4bcf-bbf3-cc0f7d2616ba" # Azure Registered App / Service Principal with the same certificate and Keyvault permissions configured
Connect-PnPOnline -Url $siteUrl -ClientId $clientID -Tenant $tenant -CertificateBase64Encoded $secretValueText

Conclusion

In this blog post, we have explored how to connect to SharePoint Online using the Connect-PnPOnline command without encountering any username/password prompts. This approach is particularly useful when creating a non-interactive PowerShell script.

We stored the certificate in Azure KeyVault and retrieved it using PowerShell commands. Subsequently, we established a connection with SharePoint Online using this certificate. Alternatively, you can store the certificate PFX file locally and use the Connect-PnPOnline cmdlet to connect to SharePoint Online.

3 thoughts on “Connect to Sharepoint Online using a Certificate in Azure KeyVault”

  1. Great post thank you. One adjustment. Step 5, there was no Secret ID within my app. Two steps I had to do for this to work were:
    1. Manually add a Secret (I set expiry for 2 years)
    2. The secret ID was the wrong value and I received an error….its the “Secret Value” that must be provided.

    Other than that you saved me a lot of headaches with this post. Appreciate it.

    Reply

Leave a Comment