<# 
.SYNOPSIS
    This Script can be used to associate a single SharePoint site with an Enterprise App Registration that uses the SharePoint Application Sites.

    This script assumes user running the script is familiar with PowerShell and has Entra access and Administrator-level access to all sites being updated. The script will need to be modified to run using a list of sites. 
	
    This script uses Interactive login.

    -- v1.0 - 02/18/2026 - RTW -- initial version

    NOTE: This script is provided without any explicitly or implicitly granted warranties or guarantees. It has been successfully used internally by Gimmal/Morae Client Services, but should not be considered production-ready off-the-shelf software.  	
	Clients are responsible for their own verification and testing in/by client's own DEV/TEST environment BEFORE using against a PROD environment.  

.DESCRIPTION 
    This script uses PnP PowerShell to assign a given site to the Sites.Selected permission of an App Registration.

.NOTES 
    1) Script should be run from a server/workstation that has the required PowerShell module installed.
	2) Script assumes that an App Registration is avaiable for Application-based PowerShell Script Authentication/Automation 
    with sufficient access to the sites/environment being updated manipulated.

    The following are some helpful links with more information on setting Sites.Selected permission settings
    # See https://www.youtube.com/watch?v=SNIF3zCYNUk
    # See https://www.dynamicpoint.com/knowledge-base/general/security/sharepoint-site-selected-permissions/

.CMD LINE
    n/a

.COMPONENT 
    Requires PowerShell v7.5.4+
    Requires PnP PowerShell (v3.1.0 PnP.PowerShell or higher)


#>

#
# ================================
# Update these Configuration variables
# ================================
# $adminUrl        -- URL to SharePoint Admin Portal
# $urlOfSiteToAdd  -- URL of the site to which the Enterprise Application should be granted access
# $AppId           -- Client (App) ID to use for authenticating the PowerShell Application connection
# $trgtAppId       -- Client (App) ID of the Enterprise Application to which the site should be added
# $displayName     -- Name to use for the Permission to be added ... e.g. "SPOCAccess" (can be anything)
# $permissionLevel -- permisssion level to grant  # Can be "Read", "Write", "Manage", or "FullControl" (Recommended)
#
$adminUrl = "https://tenant-admin.sharepoint.com" # URL to SharePoint Admin Portal
$urlOfSiteToAdd = "https://tenant.sharepoint.com/sites/sitenametoadd" #  URL of the site to which the Enterprise Application should be granted access
$AppId = "********-****-****-****-************" # Client (App) ID to use for authenticating the PowerShell Application connection
$trgtAppId = "********-****-****-****-************" # Client (App) ID of the Enterprise Application to which the site should be added
$displayName = "SPOCAccess" # e.g., "MyAppAccess"  Name to use for the Permission to be added
$permissionLevel = "FullControl" # permisssion level to grant, "FullControl" is recommended

# Connect to SharePoint Online using an administrative account (interactive login for an admin)
Connect-PnPOnline -Url $adminUrl -Interactive -ClientId $AppId -Tenant "tenant.onmicrosoft.com" -ForceAuthentication

# Grant the permission to the specific site for the target AppId
Grant-PnPAzureADAppSitePermission -AppId $trgtAppId -DisplayName $displayName -Site $urlOfSiteToAdd -Permissions $permissionLevel

#Echo the output for progress tracing
Write-Host "Granted $permissionLevel permissions to App ID $appId on site $urlOfSiteToAdd"

#Echo back
$permissionObj = Get-PnPAzureADAppSitePermission -Site $urlOfSiteToAdd
write-host $permissionObj

#To revoke any permissions in future, use the following cmdlet
#Revoke-PnPAzureADAppSitePermission -PermissionId $permissionObj.Id -Site $urlOfSiteToAdd