Authentication¶

SPClean supports two authentication methods. You must connect before using any other cmdlet.

Automated App Registration Setup (Recommended)¶

If you are a Global Administrator, you can use the included setup script to automatically create an Entra ID Application Registration with all required permissions and certificates. This replaces the manual setup steps in Methods A and B.

# Navigate to the tools directory
cd .\tools

# Run the setup script (replace 'contoso' with your tenant name)
.\Setup-SPCleanApp.ps1 -TenantName "contoso"

The script will: 1. Open a browser for you to sign in. 2. Create an App Registration named SPClean App. 3. Assign all required Microsoft Graph and SharePoint permissions. 4. Generate a self-signed certificate and store it in your Windows Certificate Store (CurrentUser). 5. Configure http://localhost for Interactive login.

Important: After the script completes, you must go to the Entra Admin Center and click Grant admin consent for the newly created app!

Method A â€” Interactive (delegated, for manual use)¶

Requires an Entra app registration configured for delegated auth.

One-time app registration setup¶

Go to Entra Admin Center â†’ App registrations â†’ New registration
Authentication blade:
- Add platform â†’ Mobile and desktop applications
- Add both redirect URIs:
  - http://localhost â† required for browser-based interactive login (PnP opens a random localhost port)
  - https://login.microsoftonline.com/common/oauth2/nativeclient
- Enable Allow public client flows = Yes
API permissions â†’ Add delegated permissions:
- Microsoft Graph: User.Read.All, Directory.Read.All, AuditLog.Read.All
- SharePoint: AllSites.FullControl
Grant admin consent

Missing http://localhost â†’ AADSTS50011

PnP PowerShell 3.x interactive auth opens a browser and redirects to http://localhost:<random-port>. If http://localhost is not listed under Mobile and desktop redirect URIs, Azure AD will reject with AADSTS50011: redirect URI does not match. Adding the port-less http://localhost covers all ports.

Connect¶

Connect-SPCTenant -TenantName contoso -ClientId '<your-app-client-id>'

A browser window opens for sign-in. You must authenticate with an account that has SharePoint Administrator or Global Administrator privileges to connect to the tenant.

Site Collection Administrator Requirement

Scanning or modifying individual sites requires Site Collection Administrator (SCA) privileges on those specific sites. If you are a SharePoint Admin but not an SCA of the target sites, use the -AddTempSiteCollectionAdmin switch on cmdlets like Get-SPCOrphanedUser to automatically elevate your permissions during execution.

Method B â€” AppOnly / certificate (automation and scheduled tasks)¶

Requires an Entra app registration with a certificate credential.

One-time app registration setup¶

Go to Entra Admin Center â†’ App registrations â†’ New registration
Certificates & secrets â†’ upload a .pfx or .cer certificate
API permissions â†’ Add application permissions:
- Microsoft Graph: User.Read.All, Directory.Read.All, AuditLog.Read.All, Sites.FullControl.All
- SharePoint: Sites.FullControl.All
Grant admin consent

Connect¶

# Sá» dá»¥ng file PFX:
$certPwd = Read-Host -AsSecureString 'Certificate password'
Connect-SPCTenant -TenantName contoso `
    -AuthMethod AppOnly `
    -ClientId    '<your-app-client-id>' `
    -CertificatePath C:\certs\spclean.pfx `
    -CertificatePassword $certPwd

# Hoáº·c sá» dá»¥ng Thumbprint (chá»©ng chá»‰ Ä‘Ã£ Ä‘Æ°á»£c install vÃ o mÃ¡y):
Connect-SPCTenant -TenantName contoso `
    -AuthMethod AppOnly `
    -ClientId    '<your-app-client-id>' `
    -CertificateThumbprint '1234567890ABCDEF'

Method C â€” AppOnly / client secret¶

$secret = Read-Host -AsSecureString 'Client secret'
Connect-SPCTenant -TenantName contoso `
    -AuthMethod AppOnly `
    -ClientId    '<your-app-client-id>' `
    -ClientSecret $secret

Legacy Authentication / Limited Functionality

Connecting with Client Secret uses legacy authentication (ACS-based) and provides limited functionality. It does not work with Microsoft Graph and limits cmdlets related to Microsoft Teams, Planner, Flow, and M365 Groups. It is highly recommended to use Certificate-based authentication or Interactive authentication instead.

Disconnect¶

Disconnect-SPCTenant

Clears the module connection state and disconnects both PnP and Microsoft Graph sessions.

Permission requirements¶

AppOnly (automation)¶

Permission	Type	API	Purpose
`Sites.FullControl.All`	Application	Microsoft Graph	Read UIL, remove users
`User.Read.All`	Application	Microsoft Graph	Verify Entra account status
`Directory.Read.All`	Application	Microsoft Graph	Detect soft-deleted accounts
`AuditLog.Read.All`	Application	Microsoft Graph	Read user sign-in activity
`Sites.FullControl.All`	Application	SharePoint	Per-site connections

Interactive (manual)¶

Permission	Type	API	Purpose
`AllSites.FullControl`	Delegated	SharePoint	PnP site connections
`User.Read.All`	Delegated	Microsoft Graph	Verify Entra account status
`Directory.Read.All`	Delegated	Microsoft Graph	Detect soft-deleted accounts
`AuditLog.Read.All`	Delegated	Microsoft Graph	Read user sign-in activity

All permissions require admin consent.

Next step¶

Quick Start â†’