Microsoft 365 グループへの接続
サイトをモダン化する場合、Microsoft 365 グループを既存の SharePoint サイトに接続できることが重要になります。 サイトが Microsoft 365 グループに接続されると、Microsoft Teams、Planner などグループに接続済みのその他のすべてのサービスの利点を活用することができます。 この接続により従来のサイトは、既定で Microsoft 365 グループに接続済みの、現行のモダン チーム サイトのようなものに一歩近づきます。
ユーザー インターフェイスから、サイトを 1 つずつ新しい Microsoft 365 グループに接続することができます。この方法は小規模な環境にお勧めです。 一方、大規模な顧客では、ユーザーに一貫したエクスペリエンスを提供するために、サイトの一括操作を行うことがよくあります。
この記事では、このような関連サイトの新しい Microsoft 365 グループへの一括操作の準備方法と、実際の操作方法を説明します。
重要
- コミュニケーション サイトの Microsoft 365 グループへの接続はサポートされていません。
- テナントではルート サイト コレクションのグループの接続はできません。
重要
モダン化ツールと他のすべての PnP コンポーネントは、それらをサポートしてくれるアクティブなコミュニティによって支援されているオープン ソース ツールです。 公式の Microsoft サポート チャネルのオープン ソース ツールのサポート用 SLA ではありません。
新しい Microsoft 365 グループに接続すると、サイトはどうなりますか
新しい Microsoft 365 グループにサイトを接続すると、さまざまな用途につながります。
- 新しい Microsoft 365 グループが作成され、使用しているサイト コレクションにそのグループが接続されます
- 新しくモダンなホーム ページがサイトに作成され、サイトのホーム ページとして設定されます
- グループの所有者がサイト コレクションの管理者になります
- グループの所有者がサイトの所有者グループに追加されます
- グループのメンバーがサイトのメンバー グループに追加されます
サイトは、Microsoft 365 グループにいったん接続されると、チーム サイトに接続されたモダン グループのように動作します。このため、接続された Microsoft 365 グループへのアクセス許可をユーザーに付与すると、そのユーザーに SharePoint サイトへのアクセス許可も付与されるほか、サイトの上に Microsoft Team を作成したり、Planner を統合したり、さまざまなことが実現できるようになります。
SharePoint ユーザー インターフェイスを使用して Microsoft 365 グループを接続する
Microsoft 365 グループをサイトに接続する方法の 1 つは、ユーザー インターフェイスで使用可能なオプションを使用することです。 ナビゲーション バーの歯車アイコンを選択すると、[新しい Microsoft 365 グループへの接続] オプションが選択できます。このオプションを選択すると、以下のスクリーンショットで示すようなウィザードが起動して、グループ接続のプロセスを進めてゆくことができます。
[サイトの操作] メニュー (歯車アイコン)
ウィザード
プログラムを使用して Microsoft 365 グループを接続する
プログラムを使用して、Microsoft 365 グループを接続する場合は、3 段階の手順に従うことをお勧めします。
- 学習
- 分析
- モダン化
手順 1: グループ接続がサイトに与える影響を学習する
サイトを接続すると生じる変化について、十分に理解することが重要です。このため、ユーザー インターフェイスのオプションを使用して、いくつかのテスト サイトを手動で接続することをお勧めします。 評価するべき重要な面は、新たに作成されるモダン ホーム ページを維持し続ける必要があるかどうかです。 スクリプトをモダン化することの一部としてカスタマイズされたホーム ページを作成できますが、既定で作成されるホーム ページでニーズを満たしている場合は、それを使用する方が望ましいと言えます。
手順 2: サイトを分析する
前のセクションで示したユーザー インターフェイスのオプションは、何百もあるサイト コレクションのグループ接続には適していません。 その場合は、API を使用してプログラム的に接続する方が理にかなっています。 ただし、グループ接続に適さないサイトもあるため、実際に実行する前に、どのサイトが接続の準備ができているかを確認することをお勧めします。
グループ接続をする準備ができているサイトを確認する助けとして、SharePoint モダン化スキャナーを使用して環境を分析できます。 このリンクには、スキャナーの実行に必要なすべての詳細が含まれています。 スキャナーを実行した後、「スキャナーの結果を理解して処理する」の記事を参照して、スキャンの結果を分析してください。
手順 3: サイトをモダン化する
一括グループ接続のプロセスは、2 つの手順で構成されます。
- 一括グループ接続のプロセスを実行するために使用する入力ファイルを準備し検証します。
- 一括グループ接続のプロセスを実行する。
一括グループ接続用の入力ファイルを作成し検証する
スキャナーを実行し、結果を処理すると、グループ接続に適したサイトを特定できます。次の手順として、一括グループ接続プロセスを実行するための CSV ファイルを準備します。 CSV ファイル形式は次の簡単なものです。
- URL 列には、グループ接続するサイト コレクションの URL を格納します。
- Alias には、使用する Microsoft 365 グループのエイリアスを格納します。 このエイリアスにスペースを含めることはできません。また、以前に使用されていないものである必要があります。
- IsPublic は、サイトの公開または非公開を指定します。
- Classification には、グループ接続後にサイトに設定するサイトの分類を格納します。 これが必要になるのは、グループへの接続後、この分類が Microsoft 365 グループ レベルで管理されるためです。
簡単な例を次に示します。
Url,Alias,IsPublic,Classification
https://contoso.sharepoint.com/sites/hrteam,hrteam,false,Medium Impact
https://contoso.sharepoint.com/sites/engineering,engineeringteam,true,Low Impact
このファイルの使用前の検証に、このセクションの最後にある PowerShell スクリプトを使用できます。 このスクリプトは、有効なサイトの URL とエイリアスを確認します。 使用しているテナントの管理センター URL を使用してこのスクリプトを更新し、実行してください。 このスクリプトは、CSV ファイルの名前を確認し、自動的にレポートを生成します。
検証スクリプトの実行時に、次のエラーが表示される場合があります。
| エラー | 説明 |
|---|---|
| AzureAD Naming policy : PrefixSuffix does contain AD attributes that are resolved based on the user running the group-connection | Azure AD で Microsoft 365 グループの名前付けポリシーを定義できます。 このポリシーにユーザー Active Directory 属性が含まれている場合、一括グループ接続では現在のユーザーを使用してすべてのサイトを処理するため、このことが問題になる場合があります。 |
| AzureAD Creation policy : adminUPN is not part of group CanCreateGroupsId that controls Microsoft 365 group creation | Azure AD グループの作成が特定のアカウントに制限されており、現在のアカウントがそれに含まれていない場合、Microsoft 365 グループの作成は失敗します。 |
| siteUrl : Alias [siteAlias] contains a space, which is not allowed | Microsoft 365 グループのエイリアスにスペースを含めることはできません。 |
| siteUrl : Classification [siteClassification] does not comply with available Azure AD classifications [ClassificationListString] | 指定したサイトの分類が、許可されている Microsoft 365 グループのサイト分類のいずれとしても定義されていません。 |
| siteUrl : Alias [siteAlias] is in the Azure AD blocked word list [CustomBlockedWordsListString] | Azure AD で禁止単語のリストが設定されており、指定された Microsoft 365 グループの名前がリスト内の禁止単語を使用している場合は、このエラーが生成されます。 |
| siteUrl : Site is already connected to a group | サイトが接続できるのは、1 つの Microsoft 365 グループのみです。したがって、いったんサイトを接続すると、それ以上グループ接続を行うことはできません。 |
| siteUrl : Alias [siteAlias] is already in use | それぞれの Microsoft 365 グループには固有のエイリアスが必要です。仮予約されたエイリアスが他の Microsoft 365 グループで既に使用されている場合、このエラーが生成されます。 |
| siteUrl : Alias [siteAlias] was already marked as approved alias for another site in this file | 仮予約されたサイト エイリアスは既に、一括グループ接続の CSV ファイルの先行する入力行で別のサイトのために定義済みです。 |
| siteUrl : Site does not exist or is not available (status = site.Status) | 指定したサイトの URL は、到達可能なサイト コレクションにはありません。 |
注:
テナント管理センターの URL (https://contoso-admin.sharepoint.com など) を含むように、以下に示すスクリプト内の $tenantAdminUrl 変数を更新してください。
スクリプトの実行中、ログ ファイルが生成されるのと同時にエラー ファイルも生成されます。エラー ファイルにはログ ファイルのサブセット (エラーのみ) が格納されます。
<#
.SYNOPSIS
Validates the CSV input file for the bulk "Office 365 Group Connects".
.EXAMPLE
PS C:\> .\ValidateInput.ps1
#>
#region Logging and generic functions
function LogWrite
{
param([string] $log , [string] $ForegroundColor)
$global:strmWrtLog.writeLine($log)
if([string]::IsNullOrEmpty($ForegroundColor))
{
Write-Host $log
}
else
{
Write-Host $log -ForegroundColor $ForegroundColor
}
}
function LogError
{
param([string] $log)
$global:strmWrtError.writeLine($log)
}
function IsGuid
{
param([string] $owner)
try
{
[GUID]$g = $owner
$t = $g.GetType()
return ($t.Name -eq "Guid")
}
catch
{
return $false
}
}
function IsGroupConnected
{
param([string] $owner)
if (-not [string]::IsNullOrEmpty($owner))
{
if ($owner.Length -eq 38)
{
if ((IsGuid $owner.Substring(0, 36)) -and ($owner.Substring(36, 2) -eq "_o"))
{
return $true
}
}
}
return $false
}
function ContainsADAttribute
{
param($PrefixSuffix)
$ADAttributes = @("[Department]", "[Company]", "[Office]", "[StateOrProvince]", "[CountryOrRegion]", "[Title]")
foreach($attribute in $ADAttributes)
{
if ($PrefixSuffix -like "*$attribute*")
{
return $true
}
}
return $false
}
#endregion
#######################################################
# MAIN section #
#######################################################
# Tenant admin url
$tenantAdminUrl = "https://contoso-admin.sharepoint.com"
# If you use credential manager then specify the used credential manager entry, if left blank you'll be asked for a user/pwd
$credentialManagerCredentialToUse = ""
#region Setup Logging
$date = Get-Date
$logfile = ((Get-Item -Path ".\" -Verbose).FullName + "\GroupconnectInputValidation_log_" + $date.ToFileTime() + ".txt")
$global:strmWrtLog=[System.IO.StreamWriter]$logfile
$global:Errorfile = ((Get-Item -Path ".\" -Verbose).FullName + "\GroupconnectInputValidation_error_" + $date.ToFileTime() + ".txt")
$global:strmWrtError=[System.IO.StreamWriter]$Errorfile
#endregion
#region Load needed PowerShell modules
#Ensure PnP PowerShell is loaded
$minimumVersion = New-Object System.Version("2.24.1803.0")
if (-not (Get-InstalledModule -Name SharePointPnPPowerShellOnline -MinimumVersion $minimumVersion -ErrorAction Ignore))
{
Install-Module SharePointPnPPowerShellOnline -MinimumVersion $minimumVersion -Scope CurrentUser -Force
}
Import-Module SharePointPnPPowerShellOnline -DisableNameChecking -MinimumVersion $minimumVersion
#endregion
#region Ensure Azure PowerShell is loaded
$minimumAzurePowerShellVersion = New-Object System.Version("2.0.0.137")
if (-not (Get-InstalledModule -Name AzureADPreview -MinimumVersion $minimumAzurePowerShellVersion -ErrorAction Ignore))
{
install-module AzureADPreview -MinimumVersion $minimumAzurePowerShellVersion -Scope CurrentUser -Force
}
Import-Module AzureADPreview -MinimumVersion $minimumAzurePowerShellVersion
$siteURLFile = Read-Host -Prompt 'Input name of .CSV file to validate (e.g. sitecollections.csv) ?'
# Get the tenant admin credentials.
$credentials = $null
$adminUPN = $null
if(![String]::IsNullOrEmpty($credentialManagerCredentialToUse) -and (Get-PnPStoredCredential -Name $credentialManagerCredentialToUse) -ne $null)
{
$adminUPN = (Get-PnPStoredCredential -Name $credentialManagerCredentialToUse).UserName
$credentials = $credentialManagerCredentialToUse
$azureADCredentials = Get-PnPStoredCredential -Name $credentialManagerCredentialToUse -Type PSCredential
}
else
{
# Prompts for credentials, if not found in the Windows Credential Manager.
$adminUPN = Read-Host -Prompt "Please enter admin UPN"
$pass = Read-host -AsSecureString "Please enter admin password"
$credentials = new-object management.automation.pscredential $adminUPN,$pass
$azureADCredentials = $credentials
}
if($credentials -eq $null)
{
Write-Host "Error: No credentials supplied." -ForegroundColor Red
exit 1
}
#endregion
#region Connect to SharePoint and Azure
# Get a tenant admin connection, will be reused in the remainder of the script
LogWrite "Connect to tenant admin site $tenantAdminUrl"
$tenantContext = Connect-PnPOnline -Url $tenantAdminUrl -Credentials $credentials -Verbose -ReturnConnection
LogWrite "Connect to Azure AD"
$azureUser = Connect-AzureAD -Credential $azureADCredentials
#endregion
#region Read Azure AD group settings
$groupSettings = (Get-AzureADDirectorySetting | Where-Object -Property DisplayName -Value "Group.Unified" -EQ)
$CheckGroupCreation = $false
$CanCreateGroupsId = $null
$CheckClassificationList = $false
$ClassificationList = $null
$CheckPrefixSuffix = $false
$PrefixSuffix = $null
$CheckDefaultClassification = $false
$DefaultClassification = $null
$CheckCustomBlockedWordsList = $false
if (-not ($groupSettings -eq $null))
{
if (-not($groupSettings["EnableGroupCreation"] -eq $true))
{
# Group creation is restricted to a security group...verify if the current user is part of that group
# See: https://support.office.com/en-us/article/manage-who-can-create-office-365-groups-4c46c8cb-17d0-44b5-9776-005fced8e618?ui=en-US&rs=en-001&ad=US
$CheckGroupCreation = $true
$CanCreateGroupsId = $groupSettings["GroupCreationAllowedGroupId"]
}
if (-not ($groupSettings["CustomBlockedWordsList"] -eq ""))
{
# Check for blocked words in group name
# See: https://support.office.com/en-us/article/office-365-groups-naming-policy-6ceca4d3-cad1-4532-9f0f-d469dfbbb552?ui=en-US&rs=en-001&ad=US
$CheckCustomBlockedWordsList = $true
$option = [System.StringSplitOptions]::RemoveEmptyEntries
$CustomBlockedWordsListString = $groupSettings["CustomBlockedWordsList"]
$CustomBlockedWordsList = $groupSettings["CustomBlockedWordsList"].Split(",", $option)
# Trim array elements
[int] $arraycounter = 0
foreach($c in $CustomBlockedWordsList)
{
$CustomBlockedWordsList[$arraycounter] = $c.Trim(" ")
$arraycounter++
}
}
if (-not ($groupSettings["PrefixSuffixNamingRequirement"] -eq ""))
{
# Check for prefix/suffix naming - any dynamic tokens beside [groupname] can be problematic since all
# groups are created using the user running the bulk group connect
# See: https://support.office.com/en-us/article/office-365-groups-naming-policy-6ceca4d3-cad1-4532-9f0f-d469dfbbb552?ui=en-US&rs=en-001&ad=US
$CheckPrefixSuffix = $true
$PrefixSuffix = $groupSettings["PrefixSuffixNamingRequirement"]
}
if (-not ($groupSettings["ClassificationList"] -eq ""))
{
# Check for valid classification labels
# See: https://support.office.com/en-us/article/Manage-Office-365-Groups-with-PowerShell-aeb669aa-1770-4537-9de2-a82ac11b0540
$CheckClassificationList = $true
$option = [System.StringSplitOptions]::RemoveEmptyEntries
$ClassificationListString = $groupSettings["ClassificationList"]
$ClassificationList = $groupSettings["ClassificationList"].Split(",", $option)
# Trim array elements
[int] $arraycounter = 0
foreach($c in $ClassificationList)
{
$ClassificationList[$arraycounter] = $c.Trim(" ")
$arraycounter++
}
if (-not ($groupSettings["DefaultClassification"] -eq ""))
{
$CheckDefaultClassification = $true
$DefaultClassification = $groupSettings["DefaultClassification"].Trim(" ")
}
}
}
#endregion
#region Validate input
LogWrite "General Azure AD validation"
if ($CheckPrefixSuffix -and (ContainsADAttribute $PrefixSuffix))
{
$message = "[ERROR] AzureAD Naming policy : $PrefixSuffix does contain AD attributes that are resolved based on the user running the group connect"
LogWrite $message Red
LogError $message
}
if ($CheckGroupCreation)
{
$groupToCheck = new-object Microsoft.Open.AzureAD.Model.GroupIdsForMembershipCheck
$groupToCheck.GroupIds = $CanCreateGroupsId
$accountToCheck = Get-AzureADUser -SearchString $adminUPN
$groupsUserIsMemberOf = Select-AzureADGroupIdsUserIsMemberOf -ObjectId $accountToCheck.ObjectId -GroupIdsForMembershipCheck $groupToCheck
if ($groupsUserIsMemberOf -eq $null)
{
$message = "[ERROR] AzureAD Creation policy : $adminUPN is not part of group $CanCreateGroupsId which controls Office 365 Group creation"
LogWrite $message Red
LogError $message
}
}
# "approved" aliases
$approvedAliases = @{}
LogWrite "Validating rows in $siteURLFile..."
$csvRows = Import-Csv $siteURLFile
foreach($row in $csvRows)
{
if($row.Url.Trim() -ne "")
{
$siteUrl = $row.Url
$siteAlias = $row.Alias
$siteClassification = $row.Classification
if ($siteClassification -ne $null)
{
$siteClassification = $siteClassification.Trim(" ")
}
LogWrite "[VALIDATING] $siteUrl with alias [$siteAlias] and classification [$siteClassification]"
try
{
# First perform validations that do not require to load the site
if ($siteAlias.IndexOf(" ") -gt 0)
{
$message = "[ERROR] $siteUrl : Alias [$siteAlias] contains a space, which not allowed"
LogWrite $message Red
LogError $message
}
elseif (($CheckClassificationList -eq $true) -and (-not ($ClassificationList -contains $siteClassification)))
{
$message = "[ERROR] $siteUrl : Classification [$siteClassification] does not comply with available AzureAD classifications [$ClassificationListString]"
LogWrite $message Red
LogError $message
}
elseif (($CheckCustomBlockedWordsList -eq $true) -and ($CustomBlockedWordsList -contains $siteAlias))
{
$message = "[ERROR] $siteUrl : Alias [$siteAlias] is in the AzureAD blocked word list [$CustomBlockedWordsListString]"
LogWrite $message Red
LogError $message
}
else
{
# try getting the site
$site = Get-PnPTenantSite -Url $siteUrl -Connection $tenantContext -ErrorAction Ignore
if ($site.Status -eq "Active")
{
if (IsGroupConnected $site.Owner)
{
$message = "[ERROR] $siteUrl : Site is already connected a group"
LogWrite $message Red
LogError $message
}
else
{
$aliasIsUsed = Test-PnPOffice365GroupAliasIsUsed -Alias $siteAlias -Connection $tenantContext
if ($aliasIsUsed)
{
$message = "[ERROR] $siteUrl : Alias [$siteAlias] is already in use"
LogWrite $message Red
LogError $message
}
elseif ($approvedAliases.ContainsKey($siteAlias))
{
$message = "[ERROR] $siteUrl : Alias [$siteAlias] was already marked as approved alias for another site in this file"
LogWrite $message Red
LogError $message
}
else
{
$approvedAliases.Add($siteAlias, $siteAlias)
LogWrite "[VALIDATED] $siteUrl with alias [$siteAlias] and classification [$siteClassification]" Green
}
}
}
else
{
$message = "[ERROR] $siteUrl : Site does not exist or is not available (status = $($site.Status))"
LogWrite $message Red
LogError $message
}
}
}
catch [Exception]
{
$ErrorMessage = $_.Exception.Message
LogWrite "Error: $ErrorMessage" Red
LogError $ErrorMessage
}
}
}
#endregion
#region Close log files
if ($global:strmWrtLog -ne $NULL)
{
$global:strmWrtLog.Close()
$global:strmWrtLog.Dispose()
}
if ($global:strmWrtError -ne $NULL)
{
$global:strmWrtError.Close()
$global:strmWrtError.Dispose()
}
#endregion
一括グループ接続のプロセスを実行する
グループ接続する必要があるサイトを定義する入力ファイルが準備できたので、実行に移ることができます。 以下の PowerShell スクリプトは、サンプル スクリプトです。グループ接続の一部として、スクリプトを足したり減らしたり、ニーズに応じて調整してください。
以下に示すサンプル バージョンのスクリプトでは、次の手順を実装します。
- 必要に応じて、サイト管理者として現在のテナント管理者を追加します。グループ接続するにはユーザー アカウントが必要です (アプリ単独では不可)。
- スキャナーのロジックに合わせて、グループ接続を妨げるサイト テンプレートや発行機能が使用されていないかどうかを確認します。
- モダンをブロックする機能が有効になっていないことを確認し、有効になっている場合は修正します。
- モダン ページの機能が有効になっていることを確認します。
- オプション: アプリケーション (例: アプリケーション カスタマイザー) を展開します。
- オプション: モダン ホーム ページを追加します。
- グループ接続の API を呼び出します。
- サイト管理者とサイトの所有者をグループの所有者として定義します。
- サイト メンバーをグループ メンバーとして定義します。
- SharePoint 管理者から、追加されたテナント管理者とサイトの所有者を削除します。
- Microsoft 365 グループから追加されたテナント管理者を削除します。
以下の PowerShell スクリプトを実行するには、テナント管理センターの URL を更新し、実行時に資格情報と CSV 入力ファイルを提供する必要があります。
注:
これはサンプル スクリプトであり、オプションの部分を更新または削除したり、さらにモダン化タスクを追加したり (SharePoint サイトのテーマ設定など) して、それぞれのユーザーの必要に合わせたものにする必要があります。 テナント管理センターの URL (https://contoso-admin.sharepoint.com など) を含むようにスクリプト内の $tenantAdminUrl 変数を更新してください。
スクリプトの実行中、ログ ファイルが生成されるのと同時にエラー ファイルも生成されます。エラー ファイルにはログ ファイルのサブセット (エラーのみ) が格納されます。
<#
.SYNOPSIS
"Office 365 Group Connects" a Classic SharePoint Online team site by attaching it to an Office Group and provisioning the default resources. Also enables the user to add a classification label and alias for the Group and enables Modern User Experience for the site.
Doesn't use parameters, rather asks for the values it needs. Optionally, supports hardcoding the use of Credential Manager (won't ask for credentials) and SharePoint admin site url.
.EXAMPLE
PS C:\> .\O365GroupConnectSite.ps1
#>
#region Logging and generic functions
function LogWrite
{
param([string] $log , [string] $ForegroundColor)
$global:strmWrtLog.writeLine($log)
if([string]::IsNullOrEmpty($ForegroundColor))
{
Write-Host $log
}
else
{
Write-Host $log -ForegroundColor $ForegroundColor
}
}
function LogError
{
param([string] $log)
$global:strmWrtError.writeLine($log)
}
function LoginNameToUPN
{
param([string] $loginName)
return $loginName.Replace("i:0#.f|membership|", "")
}
function AddToOffice365GroupOwnersMembers
{
param($groupUserUpn, $groupId, [bool] $Owners)
# Apply an incremental backoff strategy as after group creation the group is not immediately available on all Azure AD nodes resulting in resource not found errors
# It can take up to a minute to get all Azure AD nodes in sync
$retryCount = 5
$retryAttempts = 0
$backOffInterval = 2
LogWrite "Attempting to add $groupUserUpn to group $groupId"
while($retryAttempts -le $retryCount)
{
try
{
if ($Owners)
{
$azureUserId = Get-AzureADUser -ObjectId $groupUserUpn
Add-AzureADGroupOwner -ObjectId $groupId -RefObjectId $azureUserId.ObjectId
LogWrite "User $groupUserUpn added as group owner"
}
else
{
$azureUserId = Get-AzureADUser -ObjectId $groupUserUpn
Add-AzureADGroupMember -ObjectId $groupId -RefObjectId $azureUserId.ObjectId
LogWrite "User $groupUserUpn added as group member"
}
$retryAttempts = $retryCount + 1;
}
catch
{
if ($retryAttempts -lt $retryCount)
{
$retryAttempts = $retryAttempts + 1
Write-Host "Retry attempt number: $retryAttempts. Sleeping for $backOffInterval seconds..."
Start-Sleep $backOffInterval
$backOffInterval = $backOffInterval * 2
}
else
{
throw
}
}
}
}
function UsageLog
{
try
{
$cc = Get-PnPContext
$cc.Load($cc.Web)
$cc.ClientTag = "SPDev:GroupifyPS"
$cc.ExecuteQuery()
}
catch [Exception] { }
}
#endregion
function GroupConnectSite
{
param([string] $siteCollectionUrl,
[string] $alias,
[Boolean] $isPublic,
[string] $siteClassification,
$credentials,
$tenantContext,
[string] $adminUPN)
#region Ensure access to the site collection, if needed promote the calling account to site collection admin
# Check if we can access the site...if not let's 'promote' ourselves as site admin
$adminClaim = "i:0#.f|membership|$adminUPN"
$adminWasAdded = $false
$siteOwnersGroup = $null
$siteContext = $null
$siteCollectionUrl = $siteCollectionUrl.TrimEnd("/");
Try
{
LogWrite "User running group connect: $adminUPN"
LogWrite "Connecting to site $siteCollectionUrl"
$siteContext = Connect-PnPOnline -Url $siteCollectionUrl -Credentials $credentials -Verbose -ReturnConnection
}
Catch [Exception]
{
# If Access Denied then use tenant API to add current tenant admin user as site collection admin to the current site
if ($_.Exception.Response.StatusCode -eq "Unauthorized")
{
LogWrite "Temporarily adding user $adminUPN as site collection admin"
Set-PnPTenantSite -Url $siteCollectionUrl -Owners @($adminUPN) -Connection $tenantContext
$adminWasAdded = $true
LogWrite "Second attempt to connect to site $siteCollectionUrl"
$siteContext = Connect-PnPOnline -Url $siteCollectionUrl -Credentials $credentials -Verbose -ReturnConnection
}
else
{
$ErrorMessage = $_.Exception.Message
LogWrite "Error for site $siteCollectionUrl : $ErrorMessage" Red
LogError $ErrorMessage
return
}
}
#endregion
Try
{
# Group connect steps
# - [Done] Add current tenant admin as site admin when needed
# - [Done] Verify site template / publishing feature use and prevent group connect --> align with the logic in the scanner
# - [Done] Ensure no modern blocking features are enabled...if so fix it
# - [Done] Ensure the modern page feature is enabled
# - [Done] Optional: Deploy applications (e.g. application customizer)
# - [Done] Optional: Add modern home page
# - [Done] Call group connect API
# - [Done] Define Site Admins and Site owners as group owners
# - [Done] Define Site members as group members
# - [] Have option to "expand" site owners/members if needed
# - [Done] Remove added tenant admin and site owners from SharePoint admins
# - [Done] Remove added tenant admin from the Office 365 group
#region Adding admin
# Check if current tenant admin is part of the site collection admins, if not add the account
$siteAdmins = $null
if ($adminWasAdded -eq $false)
{
try
{
# Eat exceptions here...resulting $siteAdmins variable will be empty which will trigger the needed actions
$siteAdmins = Get-PnPSiteCollectionAdmin -Connection $siteContext -ErrorAction Ignore
}
catch [Exception] { }
$adminNeedToBeAdded = $true
foreach($admin in $siteAdmins)
{
if ($admin.LoginName -eq $adminClaim)
{
$adminNeedToBeAdded = $false
break
}
}
if ($adminNeedToBeAdded)
{
LogWrite "Temporarily adding user $adminUPN as site collection admin"
Set-PnPTenantSite -Url $siteCollectionUrl -Owners @($adminUPN) -Connection $tenantContext
$adminWasAdded = $true
}
}
UsageLog
#endregion
#region Checking for "blockers"
$publishingSiteFeature = Get-PnPFeature -Identity "F6924D36-2FA8-4F0B-B16D-06B7250180FA" -Scope Site -Connection $siteContext
$publishingWebFeature = Get-PnPFeature -Identity "94C94CA6-B32F-4DA9-A9E3-1F3D343D7ECB" -Scope Web -Connection $siteContext
if (($publishingSiteFeature.DefinitionId -ne $null) -or ($publishingWebFeature.DefinitionId -ne $null))
{
throw "Publishing feature enabled...can't group connect this site"
}
# Grab the web template and verify if it's a group connect blocker
$web = Get-PnPWeb -Connection $siteContext -Includes WebTemplate,Configuration,Description
$webTemplate = $web.WebTemplate + $web.Configuration
if ($webTemplate -eq "BICENTERSITE#0" -or
$webTemplate -eq "BLANKINTERNET#0" -or
$webTemplate -eq "ENTERWIKI#0" -or
$webTemplate -eq "SRCHCEN#0" -or
$webTemplate -eq "SRCHCENTERLITE#0" -or
$webTemplate -eq "POINTPUBLISHINGHUB#0" -or
$webTemplate -eq "POINTPUBLISHINGTOPIC#0" -or
$siteCollectionUrl.EndsWith("/sites/contenttypehub"))
{
throw "Incompatible web template detected...can't group connect this site"
}
#endregion
#region Enable full modern experience by enabling the pages features and disabling "blocking" features
LogWrite "Enabling modern page feature, disabling modern list UI blocking features"
# Enable modern page feature
Enable-PnPFeature -Identity "B6917CB1-93A0-4B97-A84D-7CF49975D4EC" -Scope Web -Force -Connection $siteContext
# Disable the modern list site level blocking feature
Disable-PnPFeature -Identity "E3540C7D-6BEA-403C-A224-1A12EAFEE4C4" -Scope Site -Force -Connection $siteContext
# Disable the modern list web level blocking feature
Disable-PnPFeature -Identity "52E14B6F-B1BB-4969-B89B-C4FAA56745EF" -Scope Web -Force -Connection $siteContext
#endregion
#region Optional: Add SharePoint Framework customizations - sample
# LogWrite "Deploying SPFX application customizer"
# Add-PnPCustomAction -Name "Footer" -Title "Footer" -Location "ClientSideExtension.ApplicationCustomizer" -ClientSideComponentId "edbe7925-a83b-4d61-aabf-81219fdc1539" -ClientSideComponentProperties "{}"
#endregion
#region Optional: Add custom home page - sample
# LogWrite "Deploying a custom modern home page"
# $homePage = Get-PnPHomePage -Connection $siteContext
# $newHomePageName = $homePage.Substring($homePage.IndexOf("/") + 1).Replace(".aspx", "_new.aspx")
# $newHomePagePath = $homePage.Substring(0, $homePage.IndexOf("/") + 1)
# $newHomePage = Add-PnPClientSidePage -Name $newHomePageName -LayoutType Article -CommentsEnabled:$false -Publish:$true -Connection $siteContext
# Add your additional web parts here!
# Add-PnPClientSidePageSection -Page $newHomePage -SectionTemplate OneColumn -Order 1 -Connection $siteContext
# Add-PnPClientSideText -Page $newHomePage -Text "Old home page was <a href=""$siteCollectionUrl/$homePage"">here</a>" -Section 1 -Column 1
# Set-PnPHomePage -RootFolderRelativeUrl ($newHomePagePath + $newHomePageName) -Connection $siteContext
#endregion
#region Prepare for group permission configuration
# Get admins again now that we've ensured our access
$siteAdmins = Get-PnPSiteCollectionAdmin -Connection $siteContext
# Get owners and members before the group claim gets added
$siteOwnersGroup = Get-PnPGroup -AssociatedOwnerGroup -Connection $siteContext
$siteMembersGroup = Get-PnPGroup -AssociatedMemberGroup -Connection $siteContext
#endregion
#region Call group connect API
LogWrite "Call group connnect API with following settings: Alias=$alias, IsPublic=$isPublic, Classification=$siteClassification"
Add-PnPOffice365GroupToSite -Url $siteCollectionUrl -Alias $alias -DisplayName $alias -Description $web.Description -IsPublic:$isPublic -KeepOldHomePage:$false -Classification $siteClassification -Connection $siteContext
#endregion
#region Configure group permissions
LogWrite "Adding site administrators and site owners to the Office 365 group owners"
$groupOwners = @{}
foreach($siteAdmin in $siteAdmins)
{
if (($siteAdmin.LoginName).StartsWith("i:0#.f|membership|"))
{
$siteAdminUPN = (LoginNameToUPN $siteAdmin.LoginName)
if (-not ($siteAdminUPN -eq $adminUPN))
{
if (-not ($groupOwners.ContainsKey($siteAdminUPN)))
{
$groupOwners.Add($siteAdminUPN, $siteAdminUPN)
}
}
}
else
{
#TODO: group expansion?
}
}
foreach($siteOwner in $siteOwnersGroup.Users)
{
if (($siteOwner.LoginName).StartsWith("i:0#.f|membership|"))
{
$siteOwnerUPN = (LoginNameToUPN $siteOwner.LoginName)
if (-not ($groupOwners.ContainsKey($siteOwnerUPN)))
{
$groupOwners.Add($siteOwnerUPN, $siteOwnerUPN)
}
}
else
{
#TODO: group expansion?
}
}
$site = Get-PnPSite -Includes GroupId -Connection $siteContext
foreach($groupOwner in $groupOwners.keys)
{
try
{
AddToOffice365GroupOwnersMembers $groupOwner ($site.GroupId) $true
}
catch [Exception]
{
$ErrorMessage = $_.Exception.Message
LogWrite "Error adding user $groupOwner to group owners. Error: $ErrorMessage" Red
LogError $ErrorMessage
}
}
LogWrite "Adding site members to the Office 365 group members"
$groupMembers = @{}
foreach($siteMember in $siteMembersGroup.Users)
{
if (($siteMember.LoginName).StartsWith("i:0#.f|membership|"))
{
$siteMemberUPN = (LoginNameToUPN $siteMember.LoginName)
if (-not ($groupMembers.ContainsKey($siteMemberUPN)))
{
$groupMembers.Add($siteMemberUPN, $siteMemberUPN)
}
}
else
{
#TODO: group expansion?
}
}
foreach($groupMember in $groupMembers.keys)
{
try
{
AddToOffice365GroupOwnersMembers $groupMember ($site.GroupId) $false
}
catch [Exception]
{
$ErrorMessage = $_.Exception.Message
LogWrite "Error adding user $groupMember to group members. Error: $ErrorMessage" Red
LogError $ErrorMessage
}
}
#endregion
#region Cleanup updated permissions
LogWrite "Group connect is done, let's cleanup the configured permissions"
# Remove the added site collection admin - obviously this needs to be the final step in the script :-)
if ($adminWasAdded)
{
#Remove the added site admin from the Office 365 Group owners and members
LogWrite "Remove $adminUPN from the Office 365 group owners and members"
$site = Get-PnPSite -Includes GroupId -Connection $siteContext
$azureAddedAdminId = Get-AzureADUser -ObjectId $adminUPN
try
{
Remove-AzureADGroupOwner -ObjectId $site.GroupId -OwnerId $azureAddedAdminId.ObjectId -ErrorAction Ignore
Remove-AzureADGroupMember -ObjectId $site.GroupId -MemberId $azureAddedAdminId.ObjectId -ErrorAction Ignore
}
catch [Exception] { }
LogWrite "Remove $adminUPN from site collection administrators"
Remove-PnPSiteCollectionAdmin -Owners @($adminUPN) -Connection $siteContext
}
#endregion
LogWrite "Group connect done for site collection $siteCollectionUrl" Green
# Disconnect PnP Powershell from site
Disconnect-PnPOnline
}
Catch [Exception]
{
$ErrorMessage = $_.Exception.Message
LogWrite "Error: $ErrorMessage" Red
LogError $ErrorMessage
#region Cleanup updated permissions on error
# Group connect run did not complete...remove the added tenant admin to restore site permissions as final step in the cleanup
if ($adminWasAdded)
{
# Below logic might fail if the error happened before the Group connect API call, but errors are ignored
$site = Get-PnPSite -Includes GroupId -Connection $siteContext
$azureAddedAdminId = Get-AzureADUser -ObjectId $adminUPN
try
{
Remove-AzureADGroupOwner -ObjectId $site.GroupId -OwnerId $azureAddedAdminId.ObjectId -ErrorAction Ignore
Remove-AzureADGroupMember -ObjectId $site.GroupId -MemberId $azureAddedAdminId.ObjectId -ErrorAction Ignore
# Final step, remove the added site collection admin
Remove-PnPSiteCollectionAdmin -Owners @($adminUPN) -Connection $siteContext
}
catch [Exception] { }
}
#endregion
LogWrite "Group connect failed for site collection $siteCollectionUrl" Red
}
}
#######################################################
# MAIN section #
#######################################################
# OVERRIDES
# If you want to automate the run and make the script ask less questions, feel free to hardcode these 2 values below. Otherwise they'll be asked from the user or parsed from the values they input
# Tenant admin url
$tenantAdminUrl = "" # e.g. "https://contoso-admin.sharepoint.com"
# If you use credential manager then specify the used credential manager entry, if left blank you'll be asked for a user/pwd
$credentialManagerCredentialToUse = ""
#region Setup Logging
$date = Get-Date
$logfile = ((Get-Item -Path ".\" -Verbose).FullName + "\Groupconnect_log_" + $date.ToFileTime() + ".txt")
$global:strmWrtLog=[System.IO.StreamWriter]$logfile
$global:Errorfile = ((Get-Item -Path ".\" -Verbose).FullName + "\Groupconnect_error_" + $date.ToFileTime() + ".txt")
$global:strmWrtError=[System.IO.StreamWriter]$Errorfile
#endregion
#region Load needed PowerShell modules
# Ensure PnP PowerShell is loaded
$minimumVersion = New-Object System.Version("1.3.0")
if (-not (Get-InstalledModule -Name PnP.PowerShell -MinimumVersion $minimumVersion -ErrorAction Ignore))
{
Install-Module PnP.PowerShell -MinimumVersion $minimumVersion -Scope CurrentUser
}
Import-Module PnP.PowerShell -DisableNameChecking -MinimumVersion $minimumVersion
# Ensure Azure PowerShell is loaded
$loadAzurePreview = $false # false to use 2.x stable, true to use the preview versions of cmdlets
if (-not (Get-Module -ListAvailable -Name AzureAD))
{
# Maybe the preview AzureAD PowerShell is installed?
if (-not (Get-Module -ListAvailable -Name AzureADPreview))
{
install-module azuread
}
else
{
$loadAzurePreview = $true
}
}
if ($loadAzurePreview)
{
Import-Module AzureADPreview
}
else
{
Import-Module AzureAD
}
#endregion
#region Gather group connect run input
# Url of the site collection to remediate
$siteCollectionUrlToRemediate = ""
$siteAlias = ""
$siteIsPublic = $false
# Get the input information
$siteURLFile = Read-Host -Prompt 'Input either single site collection URL (e.g. https://contoso.sharepoint.com/sites/teamsite1) or name of .CSV file (e.g. sitecollections.csv) ?'
if (-not $siteURLFile.EndsWith(".csv"))
{
$siteCollectionUrlToRemediate = $siteURLFile
$siteAlias = Read-Host -Prompt 'Input the alias to be used to group connect this site ?'
$siteIsPublicString = Read-Host -Prompt 'Will the created Office 365 group be a public group ? Enter True for public, False otherwise'
$siteClassificationLabel = Read-Host -Prompt 'Classification label to use? Enter label or leave empty if not configured'
try
{
$siteIsPublic = [System.Convert]::ToBoolean($siteIsPublicString)
}
catch [FormatException]
{
$siteIsPublic = $false
}
}
# If we are using a CSV, we'll need to get the tenant admin url from the user or use the hardcoded one
else {
if ($tenantAdminUrl -eq $null -or $tenantAdminUrl.Length -le 0) {
$tenantAdminUrl = Read-Host -Prompt 'Input the tenant admin site URL (like https://contoso-admin.sharepoint.com): '
}
}
# We'll parse the tenantAdminUrl from site url (unless it's set already!)
if ($tenantAdminUrl -eq $null -or $tenantAdminUrl.Length -le 0) {
if ($siteURLFile.IndexOf("/teams") -gt 0) {
$tenantAdminUrl = $siteURLFile.Substring(0, $siteURLFile.IndexOf("/teams")).Replace(".sharepoint.", "-admin.sharepoint.")
}
else {
$tenantAdminUrl = $siteURLFile.Substring(0, $siteURLFile.IndexOf("/sites")).Replace(".sharepoint.", "-admin.sharepoint.")
}
}
# Get the tenant admin credentials.
$credentials = $null
$azureADCredentials = $null
$adminUPN = $null
if(![String]::IsNullOrEmpty($credentialManagerCredentialToUse) -and (Get-PnPStoredCredential -Name $credentialManagerCredentialToUse) -ne $null)
{
$adminUPN = (Get-PnPStoredCredential -Name $credentialManagerCredentialToUse).UserName
$credentials = $credentialManagerCredentialToUse
$azureADCredentials = Get-PnPStoredCredential -Name $credentialManagerCredentialToUse -Type PSCredential
}
else
{
# Prompts for credentials, if not found in the Windows Credential Manager.
$adminUPN = Read-Host -Prompt "Please enter admin UPN"
$pass = Read-host -AsSecureString "Please enter admin password"
$credentials = new-object management.automation.pscredential $adminUPN,$pass
$azureADCredentials = $credentials
}
if($credentials -eq $null)
{
Write-Host "Error: No credentials supplied." -ForegroundColor Red
exit 1
}
#endregion
#region Connect to SharePoint and Azure
# Get a tenant admin connection, will be reused in the remainder of the script
LogWrite "Connect to tenant admin site $tenantAdminUrl"
$tenantContext = Connect-PnPOnline -Url $tenantAdminUrl -Credentials $credentials -Verbose -ReturnConnection
LogWrite "Connect to Azure AD"
$azureUser = Connect-AzureAD -Credential $azureADCredentials
#endregion
#region Group connect the site(s)
if (-not $siteURLFile.EndsWith(".csv"))
{
# Remediate the given site collection
GroupConnectSite $siteCollectionUrlToRemediate $siteAlias $siteIsPublic $siteClassificationLabel $credentials $tenantContext $adminUPN
}
else
{
$csvRows = Import-Csv $siteURLFile
foreach($row in $csvRows)
{
if($row.Url.Trim() -ne "")
{
$siteUrl = $row.Url
$siteAlias = $row.Alias
$siteIsPublicString = $row.IsPublic
try
{
$siteIsPublic = [System.Convert]::ToBoolean($siteIsPublicString)
}
catch [FormatException]
{
$siteIsPublic = $false
}
$siteClassification = $row.Classification
if ($siteClassification -ne $null)
{
$siteClassification = $siteClassification.Trim(" ")
}
GroupConnectSite $siteUrl $siteAlias $siteIsPublic $siteClassification $credentials $tenantContext $adminUPN
}
}
}
#endregion
#region Close log files
if ($global:strmWrtLog -ne $NULL)
{
$global:strmWrtLog.Close()
$global:strmWrtLog.Dispose()
}
if ($global:strmWrtError -ne $NULL)
{
$global:strmWrtError.Close()
$global:strmWrtError.Dispose()
}
#endregion