SharePoint Certificate Authentication Setup Guide

2026-04-07

Why Certificate Authentication?

Microsoft SharePoint requires certificate-based authentication for app-only (service principal) access when using the Microsoft 365 CLI. Client ID and secret authentication is not supported for SharePoint commands.

Prerequisites

• PowerShell (for Windows) or OpenSSL (for Linux/Mac)
• Azure AD admin access
• Existing Azure AD app registration for SharePoint access

Step-by-Step Guide

Option 1: Generate Certificate (PowerShell - Windows/Mac/Linux)

# 1. Generate a self-signed certificate
$cert = New-SelfSignedCertificate `
    -Subject "CN=GitHubActions-ABSDocs" `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -KeyAlgorithm RSA `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddYears(2)

# 2. Export certificate with private key (PFX)
$password = ConvertTo-SecureString -String "YourStrongPassword123!" -Force -AsPlainText
Export-PfxCertificate `
    -Cert $cert `
    -FilePath ".\sharepoint-cert.pfx" `
    -Password $password

# 3. Export public certificate (CER) for Azure AD
Export-Certificate `
    -Cert $cert `
    -FilePath ".\sharepoint-cert.cer"

# 4. Convert PFX to Base64 for GitHub Secret
$pfxBytes = [System.IO.File]::ReadAllBytes(".\sharepoint-cert.pfx")
$base64Pfx = [System.Convert]::ToBase64String($pfxBytes)
$base64Pfx | Out-File "sharepoint-cert-base64.txt"

Write-Host "✅ Certificate files generated:"
Write-Host "  - sharepoint-cert.pfx (for GitHub - keep secure!)"
Write-Host "  - sharepoint-cert.cer (for Azure AD)"
Write-Host "  - sharepoint-cert-base64.txt (base64 encoded for GitHub secret)"

Option 2: Generate Certificate (OpenSSL - Linux/Mac)

# 1. Generate private key and certificate
openssl req -x509 -newkey rsa:2048 -keyout sharepoint-key.pem -out sharepoint-cert.pem -days 730 -nodes \
  -subj "/CN=GitHubActions-ABSDocs"

# 2. Create PFX file (with password)
openssl pkcs12 -export -out sharepoint-cert.pfx -inkey sharepoint-key.pem -in sharepoint-cert.pem \
  -password pass:YourStrongPassword123!

# 3. Convert to Base64 for GitHub Secret
base64 sharepoint-cert.pfx > sharepoint-cert-base64.txt

# 4. Create CER file for Azure AD (DER format)
openssl x509 -in sharepoint-cert.pem -outform DER -out sharepoint-cert.cer

echo "✅ Certificate files generated:"
echo "  - sharepoint-cert.pfx (for GitHub - keep secure!)"
echo "  - sharepoint-cert.cer (for Azure AD)"
echo "  - sharepoint-cert-base64.txt (base64 encoded for GitHub secret)"

Upload Certificate to Azure AD

Method 1: Azure Portal

1. Go to Azure Portal
2. Navigate to Azure Active Directory → App registrations
3. Select your app (e.g., "GitHub Actions - ABS Docs Deployment")
4. Go to Certificates & secrets
5. Under Certificates tab, click Upload certificate
6. Select the sharepoint-cert.cer file
7. Add description: "GitHub Actions Certificate"
8. Click Add
9. Note the Thumbprint (you'll need it for verification)

Method 2: PowerShell

# Install module if needed
Install-Module -Name Az.Resources -Force -AllowClobber

# Connect to Azure
Connect-AzAccount

# Upload certificate
$appId = "YOUR_APP_ID"
$certPath = ".\sharepoint-cert.cer"

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($certPath)
$keyValue = [System.Convert]::ToBase64String($cert.GetRawCertData())

New-AzADAppCredential -ApplicationId $appId -CertValue $keyValue -EndDate $cert.NotAfter

Configure GitHub Secrets

Add these secrets to your GitHub repository:

Navigate to Repository Settings

Repository → Settings → Secrets and variables → Actions → New repository secret

Required Secrets for Certificate Authentication

Secret Name	Description	How to Get
SHAREPOINT_CERTIFICATE_BASE64	Base64-encoded PFX certificate	Contents of sharepoint-cert-base64.txt
SHAREPOINT_CERTIFICATE_PASSWORD	Password used when creating PFX	The password you set (e.g., YourStrongPassword123!)
SHAREPOINT_APP_ID	Azure AD Application ID	From Azure Portal → App registrations
SHAREPOINT_TENANT_ID	Azure AD Tenant ID	From Azure Portal → Azure Active Directory
SHAREPOINT_SITE_URL	Your SharePoint site URL	e.g., https://contoso.sharepoint.com/sites/docs
SHAREPOINT_DOCUMENT_LIBRARY	Document library name	e.g., Documentation

Optional Secret

Secret Name	Description
TEAMS_WEBHOOK_URL	Teams webhook for notifications

⚠️ Remove Old Secrets

You can now delete this secret (no longer used): - ~~SHAREPOINT_APP_SECRET~~ ❌ Not supported for SharePoint

Verify Certificate Setup

Test Locally

# Install M365 CLI
npm install -g @pnp/cli-microsoft365

# Test certificate authentication
m365 login --authType certificate \
  --certificateFile ./sharepoint-cert.pfx \
  --password "YourStrongPassword123!" \
  --appId YOUR_APP_ID \
  --tenant YOUR_TENANT_ID

# Verify access to SharePoint
m365 spo site get --url https://yourtenant.sharepoint.com/sites/yoursite

# If successful, you'll see site information

Alternative: Username/Password Authentication

⚠️ Not Recommended for CI/CD - Less secure, requires user credentials

If you cannot use certificates, the workflow supports username/password as a fallback:

Required Secrets (Username/Password)

Secret Name	Description
SHAREPOINT_USERNAME	SharePoint admin username
SHAREPOINT_PASSWORD	SharePoint admin password
SHAREPOINT_SITE_URL	Your SharePoint site URL
SHAREPOINT_DOCUMENT_LIBRARY	Document library name

Limitations: - Less secure (stores user credentials) - Requires MFA to be disabled or app password - User account could be locked/disabled - No service principal isolation

Troubleshooting

Certificate Not Working

Check Certificate Format:

# Verify PFX file
openssl pkcs12 -info -in sharepoint-cert.pfx -noout
# Should show certificate information

Check Base64 Encoding:

# Verify base64 can be decoded
cat sharepoint-cert-base64.txt | base64 -d > test-cert.pfx
# Compare file sizes
ls -lh sharepoint-cert.pfx test-cert.pfx

Azure AD App Permissions

Ensure your app has these permissions:

1. API Permissions (Azure Portal):
2. SharePoint → Application → Sites.ReadWrite.All

3. Grant admin consent

4. Site Permissions (PowerShell):

   # Install PnP PowerShell
   Install-Module PnP.PowerShell -Force
   
   # Connect
   Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/yoursite" -Interactive
   
   # Grant permissions
   Grant-PnPAzureADAppSitePermission `
       -AppId "YOUR_APP_ID" `
       -DisplayName "GitHub Actions" `
       -Permissions Write
   

Certificate Expired

Certificates are typically valid for 1-2 years. To renew:

1. Generate new certificate (follow steps above)
2. Upload new certificate to Azure AD (don't delete old one yet)
3. Update SHAREPOINT_CERTIFICATE_BASE64 and SHAREPOINT_CERTIFICATE_PASSWORD in GitHub
4. Test the deployment
5. Delete old certificate from Azure AD

Common Errors

Error	Solution
"Certificate file not found"	Check base64 encoding is complete
"Invalid password"	Verify SHAREPOINT_CERTIFICATE_PASSWORD matches PFX password
"Certificate has expired"	Generate and upload new certificate
"Permission denied"	Check app has Sites.ReadWrite.All permission
"Site not found"	Verify SHAREPOINT_SITE_URL is correct

Security Best Practices

✅ DO: - Use certificate authentication for CI/CD - Store certificates as encrypted GitHub secrets - Set reasonable expiration dates (1-2 years) - Use strong passwords for PFX files - Rotate certificates before expiry - Use least privilege permissions

❌ DON'T: - Commit certificate files to git - Share certificate files via email/chat - Use the same certificate for multiple apps - Set indefinite expiration dates - Store passwords in plain text

Certificate Renewal Checklist

Schedule certificate renewal 30 days before expiration:

• [ ] Generate new certificate
• [ ] Upload to Azure AD (keep old cert active)
• [ ] Update GitHub secrets
• [ ] Test deployment with new certificate
• [ ] Verify successful deployment
• [ ] Remove old certificate from Azure AD
• [ ] Update calendar reminder for next renewal

Summary

For Production (Recommended)

Certificate Authentication:
✅ More secure
✅ Service principal isolation
✅ No user account dependency
✅ Supports MFA
✅ Microsoft recommended

For Testing Only

Username/Password Authentication:
⚠️  Less secure
⚠️  User account dependency
⚠️  MFA complications
⚠️  Not recommended for automation

Support

If you encounter issues:

1. Verify certificate with openssl commands above
2. Test authentication locally with M365 CLI
3. Check Azure AD app permissions
4. Review GitHub Actions logs for specific error messages

Related Documentation

• Main SharePoint Deployment Guide
• Workflow Fixes Documentation
• Microsoft: Certificate-based authentication for apps
• PnP CLI for Microsoft 365

---

Last Updated: 2025-10-08
Status: Certificate authentication required for SharePoint ✅