Connect to sharepoint online using Azure KeyVault and Connect-PnPOnline

In this blog post, we will see how to connect to sharepoint online using Connect-PnPOnline powershell cmdlet. You can use this approach to connect to sharepoint online when you are creating an unattended powershell script.

Steps given in this blog post will enable you to create a connection to sharepoint online without any username / password prompts to connect. Instead we will use a self signed certificate, ClientID, tenantID and SiteURL to connect to sharepoint online.

A self signed certificate pfx file is used to create sharepoint online connection. This enables anyone having the certificate and its private key to use the app and the permissions granted to the app to connect to sharepoint online. 

You can store this certificate on your local device or a remote file server and use Connect-PnPOnline cmdlet to connect. However its recommended to store the certificate in a secure place with permission controls in place like Azure KeyVault.

Steps to connect to sharepoint online using Connect-PnPOnline with a self signed certificate stored in Azure KeyVault

1. Create a Self Signed certificate.
2. Create an Azure AD service principal / App registration.
3. Connect the certificate to the Application.
4. Create Azure Keyvault
   1. Import Self Signed certificate in Azure Keyvault
   2. Provide Get and List permissions to Azure AD service principal on Azure Keyvault
5. Retrieve Self Signed certificate from Azure Keyvault using Powershell
6. Use Connect-PnPOnline to connect to Sharepoint Online using Powershell.

1. Create Self-Signed certificate

First step is to create a self-signed certificate, To create a Self signed certificate. You need to follow Step 1 of the blog post Connect To Sharepoint Online Using Powershell.

2. Create an Azure AD service principal / App registration

Create an Azure AD service principal using Azure Active Directory -> App registration. Follow Step 2 of the blog post Connect To Sharepoint Online Using Powershell to create Azure AD service principal.

3. Connect the certificate to the Application

Next step is to connect the Self signed certificate to the Azure AD service Principal / application registered in step 2. Follow Step 3 of the blog post Connect To Sharepoint Online Using Powershell to connect the certificate to the Application.

4. Create Azure KeyVault

Once you have completed Steps 1, 2 and 3, we can now create an Azure KeyVault using below powershell command. You can also create Azure KeyVault manually by logging on to Azure Portal.

Create Azure KeyVault

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

4.1 Import self signed certificate in Azure KeyVault

Generated self signed certificate pfx file with password needs to be imported in Azure keyvault. For Importing the certificate in Azure Keyvault, please follow below steps:

• Open Azure Keyvault Mytestkeyvault001
• Click on Certificates
• Click on + Generate/Import

• On Create a certificate page. Select Method of Certificate Creation as Import.
• Certificate Name: Provide any user friendly name of the certificate.
• Upload Certificate File: Browse to the certificate pfx file.
• Password: Provide certificate pfx file password.
• Click on Create to start the Import process.

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 Azure AD service principal in Azure Keyvault. Please follow below steps to provide Get and list permissions:

• Open Azure Keyvault Mytestkeyvault001
• Click on Access policies
• Click on + Create

• On Permissions tab, Select Get under Secret permissions and Select Get and List under Certificate permissions.

• On Principal tab – Search for the service principal and select it. Click on Next to proceed. Proceed to Application and Review + Create tabs and click on Create to create the permissions.

• After creating the Application permissions, it will list it under Access policies. You can also review the permissions assigned to the service principal from Secret Permissions and Certificate Permissions.

5. Retrieve Self Signed certificate from Azure Keyvault using Powershell

To retreive the self signed certificate from Azure KeyVault, you will first need to connect to Azure using Connect-AzAccount cmdlet which is a part of Az Powershell module. If you do not have Az Powershell module installed on your device, then you may get an error that Connect-AzAccount command is not recognized.

1. To Install Az Powershell module, Use below command:

Install Az Powershell module

Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force

2. Connect to Azure using Connect-AzAccount

• $ApplicationId: Provide ClientID of Azure AD Registered App with the same certificate and KeyVault permissions configured.
• $TenantId: Provide Tenant ID of your organization. You can find tenant ID of your organization from Overview tab of Azure Active Directory on Azure portal.
• $ClientSecret: Provide Client Secret of the service principal. You can find Client Secret by going to Azure portal -> App registration -> <SPO Service Principal> -> Certificate & secrets -> Client secrets.

If you do not have created a ClientSecret, then you can click on + 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 Client Secret Value not Secret ID for the commands/script.

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

3. Use Get-AzKeyVaultSecret cmdlet to retrieve the Certificate in a Powershell variable.

• $VaultName: Provide Azure keyvault name
• $certName: Provide 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 cmdlet to connect to Sharepoint online

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

• $tenant: Provide your organization’s tenant’s name
• $siteurl: Provide sharepoint online site URL to connect.
• $clientID: Provide ClientID of Azure AD 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

We have seen in this blog post, how you can connect to sharepoint online using Connect-PnPOnline command without any username / password prompts. This is useful when you are creating a non-interactive powershell script.

We have stored the certificate in Azure KeyVault and fetched it using powershell commands. Then we have created a connection with sharepoint online using this certificate. You can also store the certificate pfx file locally and use connect-pnponline cmdlet to connect to sharepoint online.