Certificate based authentication for SharePoint Online

Purpose

o365-connect-spo-cert.ps1 manages certificate-based authentication for SharePoint Online (SPO) admin access.

It supports two exclusive modes:

1. -GenerateLocalCertificate: create a local certificate (and optional PFX), with optional Entra app provisioning.
2. -UseCertificateAuth: connect to SPO Admin Center using app + certificate authentication.

What The Script Does

At runtime the script:

1. Resolves runtime paths relative to the script location.
2. Ensures the SharePoint Online module is installed, optionally updated, and imported.
3. Validates that Connect-SPOService supports certificate-auth parameters.
4. Runs exactly one mode (GenerateLocalCertificate or UseCertificateAuth).
5. Handles errors with targeted troubleshooting hints.
6. Returns 0 on success and 1 on failure.

Prerequisites

PowerShell and Platform

• Windows PowerShell 5.1 or PowerShell 7+.
• Elevated permissions may be required for module install/update.

Required Module

• microsoft.online.sharepoint.powershell

The script can install/update this module automatically unless -noupdate is used.

Permissions (Only if using -ProvisionEntraApp)

The operator signing in with device code must be able to:

• Create/update Entra applications and service principals.
• Grant admin consent app roles.

Provisioning requests these application permissions for the created app:

• SharePoint Online: Sites.FullControl.All
• Microsoft Graph: Application.Read.All

Parameters (Operationally Important)

Mode Control

• -GenerateLocalCertificate
• -UseCertificateAuth

Exactly one must be specified.

General Controls

• -noprompt: non-interactive operation where possible.
• -noupdate: skip module version check/update.
• -enableLog: start transcript logging to o365-connect-spo-admin.txt in the parent folder of the script directory.

Certificate Generation

• -GeneratedCertSubject (default: O365-SPO-AppAuth)
• -GeneratedCertYearsValid (default: 2)
• -GeneratedCertOutputPath (default: parent of script directory)
• -ExportGeneratedPfx
• -GeneratedPfxPassword

Certificate Auth Inputs

• -Tenant
• -ProfileName
• -AdminUrl (for example https://contoso-admin.sharepoint.com)
• -AppId
• -CertificateThumbprint
• -CertificateMapPath

Entra Provisioning (optional, generation mode only)

• -ProvisionEntraApp
• -AppDisplayName
• -SetupClientId (default device-code client ID)
• -CopyDeviceCodeToClipboard

Certificate Profile Map (JSON)

When -CertificateMapPath is not provided, the script searches these locations (in order):

1. cert-export/o365-spo-admin-cert-auth.json in script parent directory
2. o365-spo-admin-cert-auth.json in script parent directory
3. cert-export/o365-spo-admin-cert-auth.json in script directory
4. o365-spo-admin-cert-auth.json in script directory

If none exist, default write target is:

• cert-export/o365-spo-admin-cert-auth.json in script parent directory

Expected profile fields:

• name
• tenant
• adminUrl
• appId
• certificateThumbprint
• pfxPath

Mode 1: Generate Local Certificate

Basic execution

.\o365-connect-spo-cert.ps1 -GenerateLocalCertificate

Typical output

• Self-signed cert in Cert:\CurrentUser\My
• Exported .cer
• Optional exported .pfx

With Entra app provisioning

.\o365-connect-spo-cert.ps1 `
  -GenerateLocalCertificate `
  -ProvisionEntraApp `
  -Tenant contoso.onmicrosoft.com `
  -AdminUrl https://contoso-admin.sharepoint.com `
  -AppDisplayName O365-SPO-AppAuth-Contoso `
  -ExportGeneratedPfx

Provisioning flow:

1. Device-code sign-in to Microsoft Graph.
2. Resolve SPO and Graph service principals.
3. Create or reuse app registration.
4. Upload certificate to app key credentials.
5. Create/reuse service principal.
6. Grant Sites.FullControl.All and Application.Read.All.
7. Upsert JSON profile map entry atomically.

Important operational note:

• New app role grants may take about 15-30 minutes to replicate.

Mode 2: Use Certificate Authentication

Basic execution from profile map

.\o365-connect-spo-cert.ps1 -UseCertificateAuth -Tenant contoso.onmicrosoft.com

Fully explicit execution

.\o365-connect-spo-cert.ps1 `
  -UseCertificateAuth `
  -Tenant contoso.onmicrosoft.com `
  -AdminUrl https://contoso-admin.sharepoint.com `
  -AppId 11111111-2222-3333-4444-555555555555 `
  -CertificateThumbprint ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234

Connection flow:

1. Resolve profile data from JSON map (if available).
2. Fill missing values from profile.
3. Derive AdminUrl from tenant if possible.
4. Resolve certificate from local stores (CurrentUser\My, then LocalMachine\My).
5. If not found, attempt PFX import from candidate paths.
6. Validate private key presence and expiration.
7. Disconnect existing SPO session (if any).
8. Connect with Connect-SPOService using best available certificate parameter set.
9. Print connected center + certificate/app details.

Non-Interactive Operation

Use -noprompt for unattended runs. Combine with explicit parameters to avoid selection prompts:

.\o365-connect-spo-cert.ps1 `
  -UseCertificateAuth `
  -noprompt `
  -Tenant contoso.onmicrosoft.com `
  -AdminUrl https://contoso-admin.sharepoint.com `
  -AppId 11111111-2222-3333-4444-555555555555 `
  -CertificateThumbprint ABCD1234ABCD1234ABCD1234ABCD1234ABCD1234

Logging and Diagnostics

Transcript log

Enable with:

.\o365-connect-spo-cert.ps1 -UseCertificateAuth -enableLog

Log file:

• o365-connect-spo-admin.txt in script parent directory

Verbose and debug

Because the script is declared with CmdletBinding(), use:

.\o365-connect-spo-cert.ps1 -UseCertificateAuth -Verbose -Debug

Common Failures and Responses

Module or cmdlet capability issues

• Symptom: certificate-auth parameters not available on Connect-SPOService.
• Action: update microsoft.online.sharepoint.powershell and rerun.

Certificate not found/private key missing

• Symptom: thumbprint resolution or private key errors.
• Action: ensure cert exists in CurrentUser\My or LocalMachine\My and includes private key; import matching PFX if needed.

App permission/consent delays

• Symptom: access denied or insufficient privileges immediately after provisioning.
• Action: wait 15-30 minutes for RBAC replication, then retry.

Missing required inputs in auth mode

• Symptom: missing one or more of Tenant, AdminUrl, AppId, CertificateThumbprint.
• Action: supply directly or via a valid profile in the certificate map JSON.

Operational Best Practices

1. Keep PFX files secured and remove unneeded exports.
2. Rotate certificates before expiry (script warns at 30 days).
3. Use distinct app display names per tenant/environment.
4. Prefer profile map entries for repeatable operations.
5. Use -noprompt + explicit inputs for scheduled automation.

Quick Command Reference

# Generate cert only
.\o365-connect-spo-cert.ps1 -GenerateLocalCertificate

# Generate cert + provision app + profile map
.\o365-connect-spo-cert.ps1 -GenerateLocalCertificate -ProvisionEntraApp -Tenant contoso.onmicrosoft.com -AdminUrl https://contoso-admin.sharepoint.com -ExportGeneratedPfx

# Connect using profile map lookup
.\o365-connect-spo-cert.ps1 -UseCertificateAuth -Tenant contoso.onmicrosoft.com

# Connect with explicit values
.\o365-connect-spo-cert.ps1 -UseCertificateAuth -Tenant contoso.onmicrosoft.com -AdminUrl https://contoso-admin.sharepoint.com -AppId <app-id> -CertificateThumbprint <thumbprint>