Category Archives: Software

Sites.Selected API permissions for SharePoint access

7 Replies

Sites.Selected permissions are required to get access to only a specific SharePoint sites using Microsoft Graph API and/or SharePoint API (since Microsoft announced EOL of SharePoint App-only service principals, Sites.Selected is the only option going forward). Below are

Brief overview of Sites.Selected

Historically, we utilized so called SharePoint app-only service principals to get unattended (daemon/service) access to one specific site programmatically. Initially in on-prem, later in SPO. We used to get SharePoint app-only service principals via appregnew.aspx and provide permissions via appinv.aspx page. SharePoint app-only principals allow calls to SharePoint (REST) API and usage of SharePoint CSOM via ACS-based authentication.

Then Microsoft started developing Graph API. You’d need to register your app in Azure to get App Id and App secret to authenticate to Microsoft Graph API. You’d also configure specific API permissions for this app to get access to services you need (SharePoint, Exchange, Teams etc.). Unfortunately, for a long time there were no options to get access to only one specific site with Graph API. Available API permissions (e.g. Sites.Read.All) allowed access to all SharePoint sites in tenant.

Then, in 2021 Microsoft introduced Graph API “Sites.Selected” application permissions. Hooray! But the problem was devs had to have two service principals – new Sites.Selected to call Graph API and classic SP-App-only to call SharePoint API. Later, in 2022 Microsoft added SharePoint “Sites.Selected” API permissions – so both APIs are available for a single App Id (more App-Only and Sites.Selected history details…).

Long story short, below are the detailed steps to configure Sites.Selected for you unattended app access to SharePoint site.

Steps to get and configure Sites.Selected permissions

1. Register an application in Azure (Entra Id) via Azure portal GUI, PowerShell script or helpdesk/servicedesk request. E.g. with GUI you’d login to portal.azure.com,
then “Entra Id” -> “App registrations” and select “+ New registration”:

With PowerShell you’d do it with e.g. Register-PnPEntraIDApp cmdlet.

If you are not allowed to register an Entra Id app due to restrictions in your company – connect with your IT/admins, as there must me some way to request an app.

Once you get an application registration and you are this app owner – you should be able to navigate to your app registration in Azure Portal and configure it (see Step 2 and below).

2. Update the app “API permissions” – you’d need both – MS Graph API Sites.Selected and SharePoint Sites.Selected application API permissions configured:

Adding Sites.Selected API permissions via Azure Portal

Request tenant admin consent for your API permissions. Finally your app registration “API permissions” should look like:

How your app registration "API permissions" should look like for Sites.Selected - Graph and SharePoint APIs

3. App Secret or Certificate
Under Certificates and secrets – generate client secret, copy secret value to safe location.

Or you can get a certificate (obtain trusted or create self-signed), and upload it to your app registration. Certificates are considered as more secure option.

4. At the Overview page – grab your app client id and tenant id :

At this moment, having tenant id, app (client) id and client secret (or certificate) – you should be able to authenticate against Microsoft 365 tenant with app-only authentication path, but should not be able to access any site.

Having just Sites.Selected API permissions configured for app does not mean your app has access to any SharePoint site automatically. Access for the app to a specific site is provided by SharePoint team via another Graph API call. That leads us to the next step.

5. Application access to SharePoint site
You need to request this from your SharePoint service admin (or if you are an admin – DIY), but access needs to be provided for the specific app to the specific site with specified permissions (Read-Only or Read/Write or Manage or Full Control)
– Here is the Graph API
– Here is PowerShell PNP cmdlet

Interesting that MS Graph advertises 3 possible roles – read, write and owner, but PNP team says you can select from 4 roles – Read, Write, Manage or FullControl. Obviously,

  • Read role allows an app to read site content;
  • Write role is similar to “Contributor” user permissions – it allows CRUD operations against list items (library documents and metadata)
  • Manage role allows create/update/delete lists/libraries
  • FullControl is full control

At this moment you should be able to access SharePoint sites. How? See below:

Use Sites.Selected permissions

Once your SharePoint tenant/service admin confirmed that access has been provided for you app to specific SharePoint site/sites – you can use app client id and client secret (or certificate) to work with SharePoint from your code using MS Graph API or SharePoint API. Exact technique depends on language/platform you use, but there are some good tutorials published:

Generally, this Sites.Selected permissions allows you to make calls that are documented under “Files” and “Sites and Lists” Graph API documentation. I.e. get site details, get site lists/libraries, create lists and libraries, CRUD operations against list items, download/upload library documents – all within the specific site. Sites.Selected permissions does not allow search operations, anything related to group or team etc.

If you are facing issues – first of all you’d try to isolate the issue – is it permissions to blame or something else. To ensure permissions for your app were provided correctly – you can validate your app access to the target SharePoint site with simple PowerShell scripts: here is the sample code

Important Note: Sites.Selected API permissions allows you call Microsoft Graph API with client Id and client secret or certificate. Calling SharePoint API with client secret is not supported. You have to use certificate to call SharePoint API.

Calls to SharePoint API with client Id and client secret are possible only if ACS-based permissions are provided for the app to the site (with appinv.aspx), which is strictly not recommended due to announced App-Only (ACS) retirement – see updates in the end of the article.

Secure your credentials

You should not hard-code your secret as you do not want your credentials be leaked. So you need to secure your secrets in production. Solutions for secrets are included in cloud providers offerings, you can also use environment variables. If you are hosting your application in Azure – consider using key vault to keep your secrets. You can configure managed identity for your application and provide access to the key vault for you application managed id. (Actually, if your app is running in Azure – it is possible to provide permissions for your app directly – via managed identity. This is considered as even more secure setup – no app registration and no key vault is needed as there is no credentials to save, but that’s a separate story: Connecting to Microsoft 365 and Graph API from the Azure Function App via Managed Identity).

Govern Sites.Selected permissions

(For SharePoint admins).

Existing admins API/cmdlets allows yo to provide Sites.Selected permissions for specific app to specific site, and to get Sites.Selected permissions provided to the specific site. But there is no API/cmdlet for the specific app to get all sites (with permissions) this app has access to. Meantime as SharePoint admin if you keep providing permissions upon users/devs requests – after some time you have no idea what app has access to what site with what level of access, especially in large organizations. Surely you can (and should) pull reports on all registerd apps with access to SharePoint, but…

There is a solution developed by Joe Rodgers (Microsoft). This solution use SharePoint list as an inventory/storage and Power Automate flows to pull data from Entra Id and SharePoint and provides kind of dashboard so you can review details of all app registrations in the tenant with at SharePoint Online permission. Cool!

Note: you would not provide Sites.Selected permissions just upon user/developer request. You’d always get an approval from target site owner. Target site owner must understand that application will have permanent unattended access to entire SharePoint site with permissions specified (read or write or manage or full control).

Sites.Selected permissions provisioning automation

(for SharePoint admins)

Generally, to provide an Application with Sites.Selected API permissions configured access to a specific site, SharePoint admin would run a set of PowerShell commands (or C# program or…) to ensure the client id exists, API permissions are configured and consented, to get app owners, target site owners, to get existing app permissions etc. Finally, admin would provide permissions and validate that permissions were provided correctly. It does not take long…

But in medium and large environments number of requests could be significant enough to think of automation. I do have a separate article and video on Sites.Selected permissions provisioning automation.

Classic ACS permissions vs Sites.Selected permissions

Note: ACS-based permissions are deprecated:
Your SharePoint admin doesn’t allow site owners to create/update ACS principal ⋆ Vladilen Microsoft 365 engineer

Though Sites.Selected is our choice going forward, old classic ACS-based App-only permissions have some advantages (unique features) Sites.Selected does not have, e.g. ability to provide permissions not to entire site, but to specific list or subsite only. You can get more details checking this article for Comparison between Azure Apps and Entra Id Sites.Selected API permissions vs SharePoint app-only spn and ACS-based permissions.

Update:
Microsoft announced ACS permissions (app-only principals) retirement in 2026. So using ACS for any new development is not recommended.

It may be acceptable to grant ACS permissions to existing legacy custom applications or third-party or Microsoft apps/web apps (e.g. Alteryx, Azure Data Factory) – applications that only support a client ID and secret and use the SharePoint API under the hood – but only to avoid disruption to business processes and keeping in mind that ACS will expire soon, so these applications must be replaced/updated before 2026.

Here is How to prepare your tenant for Azure ACS retirement

Update: Microsoft is implementing granular (permissions to list, item or file) alongside with Sites.Selected permissions. Original implementations of Sites.Selected allowed access to entire site collection only. With new ‘Lists.SelectedOperations.Selected’, ‘ListItems.SelectedOperations.Selected’ and ‘Files.SelectedOperations.Selected’ permissions it is possible to provide application permissions to list, library or list item or particular document (reference).

References

SharePoint AppRegNew.aspx and AppInv.aspx

2 Replies

There are well-known SharePoint app-only service principals and ACS-based permissions. It is kind of old-school way – introduced as part of Add-Ins for SharePoint 2013 – to get unattended access to SharePoint site (application access, i.e. access without user presence). Such apps are called daemon apps or service apps or background jobs etc…

Microsoft announced retirement of ACS in 2026 and takes measures to stop using ACS in new and existing tenants. For you to smoothly switch to new, recommended Entra Id based service principals and permissions – it is important to know some details about classic app-only service principals and ACS-based permissions.

As you know, any access is a two-step procedure:

  • Authentication, when systems ensures you are indeed the one you claim you are
  • Authorization, when system grants you access to the resource, as it knows that this id is allowed to access such and such resource with these permissions

So, when it comes to deprecated SharePoint app-only service principals and ACS-based permissions, AppRegNew is responsible for authentication and AppInv is responsible for authorization.

AppRegNew.aspx

To get a SharePoint app-only service principal – you’d need to register a new one at any SharePoint site using the AppRegNew.aspx page. This page is not available from GUI, so you’d need to type the Url manually. You’d need to be a site collection admin to register a new app.

Let say, your site Url is “https://YourTenant.sharepoint.com/teams/YourSite“.
Then this appregnew page’s Url would be
“https://YourTenant.sharepoint.com/teams/YourSite/_layouts/15/appregnew.aspx“

If you go to this page, you’ll see (*) something like

You’d click generate client id, then generate client secret and type your app display name. I usually use “localhost” as app domain and “https://localhost” as redirect Url.

If all good – you’d get app id (client id) and app secret (client secret) and you’d be able to authenticate to your SharePoint site.

AppInv.aspx

Providing permissions for your SharePoint app-only service principal to your SharePoint site is done using AppInv.aspx page. This page is also not available from GUI, so you’d need to type the Url manually again. You’d need to be a site collection admin to use this page.

Let say, your site Url is “https://YourTenant.sharepoint.com/teams/YourSite“.
Then this appinv page’s Url would be
“https://YourTenant.sharepoint.com/teams/YourSite/_layouts/15/appinv.aspx“

If you go to this page, you’ll see (*) something like

At this moment – you need to enter app (client) id here and click lookup – so all the app metadata would be populated, then you’d need to enter Permission Request XML.
Via this “Permission Request XML” you are specifying exact permissions your app will have in this site. E.g. you can specify scope – all site collection or one specific subsite (web) or even one specific list or library. Also you can specify permissions level – e.g. read, read/write, manage or full control. This is tricky, but let me share some examples with you.

Permission Request XML for the app to have full control over entire site collection:

<AppPermissionRequests AllowAppOnlyPolicy="true">  
   <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" 
    Right="FullControl" />
</AppPermissionRequests>

Permission Request XML for the app to have read access to a subsite (web):

<AppPermissionRequests AllowAppOnlyPolicy="true">  
  <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" 
   Right="Read" />
</AppPermissionRequests>

Permission Request XML for the app to have read/write access to a list/library:

<AppPermissionRequests AllowAppOnlyPolicy="true">  
   <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" 
    Right="Write" />
</AppPermissionRequests>

Any mistake in XML might prevent app access, so be very careful.

Finally, your AppInv.aspx page would look like

If you specify scope as web – you’d do it on the specific web url, e.g.
“https://YourTenant.sharepoint.com/teams/YourSite/SubSite/_layouts/15/appinv.aspx”

If you specify scope as list – you’d do it on the specific web url, e.g.
“https://YourTenant.sharepoint.com/teams/YourSite/SubSite/_layouts/15/appinv.aspx”
and after you click “Save” – there will be a page – you’ll be asked to choose a list from available web lists.

After all, you’ll be asked to confirm that you trust the app:

And after that your app (SharePoint app-only service principal) will have access (ACS-based access) to you site.

AppPrincipals.aspx

From site settings page (/_layouts/15/settings.aspx) you should be able to see apps registered on your site with “Site app permissions” or “Site collection app permissions” links available via GUI. That would be “appprincipals.aspx” page.

Update Since July 2025 – modern apps (Entra id apps) appears under AppPrincipals.aspx page as well (see details here). Unfortunately, AppPrincipals.aspx page, you cannot see what kind of app has permissions to your site, what kind of permissions were provided, or secret expiration time. Some data can be pulled via PowerShell with Get-PnPAzureACSPrincipal though…

Possible complications

After Microsoft announced retirement of ACS – you can see this message on appinv and appregnew pages:

You might also see “Your SharePoint tenant admin doesn’t allow site collection admins to create an Azure Access Control (ACS) principal” message at appregnew page and “Your SharePoint tenant admin doesn’t allow site collection admins to update app permissions. Please contact your SharePoint administrator.” at appinv page.

That’s because a recent update to Microsoft 365 (MC660075) pushed by Microsoft in Aug/Sep 2023 changes default behavior so only tenant administrators can create or update ACS service principal by default.

If you are facing issues above – or you want to switch to modern Entra Id service principals, but by some reasons you need ACS-based permissions – here is the article on “Entra Id vs ACS for SharePoint and how to survive during transition period“

References

Connecting to Microsoft 365 SharePoint and Graph API from Azure Function App

Leave a reply

Let say you need to run some code against Microsoft 365 on a scheduled basis. For this, you can use Azure Function App and timer-triggered Functions. From the code you’d call Microsoft Graph API and/or SharePoint API, so you’d need your Function somehow to get credentials on the fly from the KV and use it to call APIs. For this – you’d have a key vault where credentials will be be stored and retrieved by functions when needed. How does KV know if it’s ok to share secrets with the function app? Below I’ll share step-by-step how to create, configure and secure an Azure Function with system-assigned managed identity, and Azure Key Vault.

Update: you can make it even more secure – you can assign permissions directly to function, eliminating credentials and key vault. I created a KBA: Connecting to Microsoft 365 and Graph API from the Azure Function App via Managed Identity

Below is a “classic” approach with client id, client secret and a key vault.

First, we’ll create a resource group, e.g. “Azure-Func-Secured”.

Next, we’ll create a function app:

We’ll avoid the default “Flex Consumption” service plan (as it is Linux-only and does not support dependencies) and select “Consumption” a hosting option for now:

Runtime stack we’ll be using is PowerShell Core 7.4, but you can choose your own (options are – Python, .Net (C#), Node.js, Java). Let us leave other configuration settings by default (e.g. Enable Public access: On) for now, we’ll fix (secure) it later.

Ok, the function app has been created. Notice that app service plan, application insights and storage account, as well as some other services were created automatically under the same resource group:

Now we can create one or more functions under this function app, also we’d need to create a key vault and a registered app. Let us start with function and VS Code would be our environment of choice.

Let us start Visual Studio Code in a separate folder. Ensure you have “Azure Functions”, “Azure Resources” and PowerShell extensions by Microsoft. You’d sign-in to Azure:

and create a function project:

You’d choose “Timer triggered” function (as we need the function running on schedule), the function name would be MyScheduledFunct01 and we’d leave the default schedule as “0 */5 * * * *” – so our function will be triggered every 5 minutes.

Let us deploy the function right away and see if it works. For this, we can use “deploy” icon under “WORKSPACE” panel:

or “Deploy to function app” option from the function app context pop-up menu under the Azure “RESOURCES” panel:

After successful deployment give it some time, then check function invocations and ensure function is triggered an running:

Next, we’d update “requirements.psd1” to include Azure Key Vault and PnP PowerShell modules as it takes some time for the function app to pull in and install dependencies. Requirements.psd1:

# This file enables modules to be automatically managed by the Functions service.
# See https://aka.ms/functionsmanageddependency for additional information.
#
@{
    # For latest supported version, go to 'https://www.powershellgallery.com/packages/Az'. Uncomment the next line and replace the MAJOR_VERSION, e.g., 'Az' = '5.*'
    # 'Az' = 'MAJOR_VERSION.*'
    'Az.KeyVault' = '6.*'
    'PnP.PowerShell' = '2.*'
}

And we’d update function itself to monitor if dependencies are installed, than we’d deploy the function again so time would work for us. MyScheduledFunction/run.ps1:

# Input bindings are passed in via param block.
param($Timer)
$currentUTCtime = (Get-Date).ToUniversalTime()
if ($Timer.IsPastDue) {
    Write-Host "PowerShell timer is running late!"
}
Write-Host "PowerShell timer trigger function ran! TIME: $currentUTCtime"
#############################################################################################
Write-Host "Check modules installed:"
Import-Module PnP.PowerShell 
Import-Module Az.KeyVault
Get-Module PnP.PowerShell
Get-Module Az.KeyVault
Write-Host "Check command available:"
Get-Command -Name Connect-PnPOnline -Module PnP.PowerShell

At first, we might see warning like “The first managed dependency download is in progress, function execution will continue when it’s done. Depending on the content of requirements.psd1, this can take a few minutes. Subsequent function executions will not block and updates will be performed in the background.”. So we’d just wait.

After some time the function will be able to use required modules. Here is the invocation output example:

App Registration
To get unattended access to SharePoint (or Teams or Exchange etc.) as a service (daemon) application – we need credentials. It is done via “App Registration” under Entra Id (Azure AD) – here is the detailed step-by-step guide on registering apps in Azure.

Finally, we’d have a service principal with permissions we need:

We do not hard-code secrets, so let us create a key vault to keep secrets safe:

We’d leave all other configuration option by default, including “Azure role-based access control”, Allow access from: All Networks etc.

Here is the trick: even if I created this key vault and have an admin-level access, I’m not able to work with secrets values. So I need to provide additional access to myself. Being at the key vault, navigate to “Access control (IAM)” and add role assignment…

We’d select “Key Vault Secrets Officer”, next, select members… and select own name:

From this moment you should be able to CRUD secrets with values.

Now, let us generate a secret under App registration and copy secret value:

Then navigate to the Key Vault -> Object/Secrets -> Generate/Import – and save the secret value there:

Now you can get this secret… but the function cannot reach the secret… Here is the proof. Let us update the function code with:

Write-Host "Get secret from the key vault:"
$vaultName = "azure-func-secrets"
$secretName = "azure-func-secured-01"
$kvSecret = Get-AzKeyVaultSecret -VaultName $vaultName -Name $secretName -AsPlainText
Write-Host "Secret:" $kvSecret.Substring(0,3)

and check the function output. You’d see something like (which is not very descriptive):

ERROR: Run Connect-AzAccount to login. Exception : Type : System.Management.Automation.PSInvalidOperationException ErrorRecord : Exception : Type : System.Management.Automation.ParentContainsErrorRecordException Message : Run Connect-AzAccount to login. HResult : -2146233087 CategoryInfo : InvalidOperation: (:) [], ParentContainsErrorRecordException FullyQualifiedErrorId : InvalidOperation TargetSite : Name : get_DefaultContext DeclaringType : [Microsoft.Azure.Commands.ResourceManager.Common.AzureRMCmdlet] MemberType : Method Module : Microsoft.Azure.PowerShell.Clients.ResourceManager.dll Message : Run Connect-AzAccount to login. Source : Microsoft.Azure.PowerShell.Clients.ResourceManager HResult : -2146233079 StackTrace : at Microsoft.Azure.Commands.ResourceManager.Common.AzureRMCmdlet.get_DefaultContext() at Microsoft.Azure.Commands.KeyVault.Models.KeyVaultCmdletBase.get_DataServiceClient() at Microsoft.Azure.Commands.KeyVault.GetAzureKeyVaultSecret.ExecuteCmdlet() at Microsoft.WindowsAzure.Commands.Utilities.Common.CmdletExtensions.<>c__31.<ExecuteSynchronouslyOrAsJob>b__3_0(T c) at Microsoft.WindowsAzure.Commands.Utilities.Common.CmdletExtensions.ExecuteSynchronouslyOrAsJob[T](T cmdlet, Action1 executor) at Microsoft.WindowsAzure.Commands.Utilities.Common.CmdletExtensions.ExecuteSynchronouslyOrAsJob[T](T cmdlet) at Microsoft.WindowsAzure.Commands.Utilities.Common.AzurePSCmdlet.ProcessRecord() CategoryInfo : CloseError: (:) [Get-AzKeyVaultSecret], PSInvalidOperationException FullyQualifiedErrorId : Microsoft.Azure.Commands.KeyVault.GetAzureKeyVaultSecret InvocationInfo : MyCommand : Get-AzKeyVaultSecret ScriptLineNumber : 19 OffsetInLine : 13 HistoryId : 1 ScriptName : C:\home\site\wwwroot\myScheduledFunction\run.ps1 Line : $kvSecret = Get-AzKeyVaultSecret -VaultName $vaultName -Name $secretName -AsPlainText Statement : Get-AzKeyVaultSecret -VaultName $vaultName -Name $secretName -AsPlainText PositionMessage : At C:\home\site\wwwroot\myScheduledFunction\run.ps1:19 char:13 + $kvSecret = Get-AzKeyVaultSecret -VaultName $vaultName -Name $secretN … + ~~~~~~~~~~~~~ PSScriptRoot : C:\home\site\wwwroot\myScheduledFunction PSCommandPath : C:\home\site\wwwroot\myScheduledFunction\run.ps1 InvocationName : Get-AzKeyVaultSecret CommandOrigin : Internal ScriptStackTrace : at , C:\home\site\wwwroot\myScheduledFunction\run.ps1: line 19 PipelineIterationInfo : 0 1

So, how’d we allow key vault access for the function app? It’s as simple as that:
– first, we’d need some identity assigned to function app
– second, we’d provide access to the key vault to this identity

Managed Identity: assign an identity to the function.
For this, you’d go to function Settings/Identity, and under System Assigned, you’d switch status to On and Save settings.

Then, you’d go to your key vault, Access Control (IAM) and add role assignment. But this time, you’d select the role “Key Vault Secrets User” (more about roles), and “Assign access to” Managed Identity, and select members – select your function app identity (notice, identity is assigned to function app, so all functions under the app will be able to use the identity):

Now, we’d check the next function invocation detail, and voila:

You can see that azure function was able on the fly to pull secret from the key vault, so now we should be able to use these credentials to access SharePoint.

As you know, having client id and client secret would allow you to call MS Graph API. But calling SharePoint API would require authentication with a certificate. “PnP.PowerShell” module use both APIs under the hood, so we’d need a certificate to connect to tenant and work with SharePoint using “PnP.PowerShell” module. Please refer to this article on how to run Connect-PnPOnline with Certificate stored in the Key Vault.

Securing Azure Function

Out-of-the-box Azure Function App is created in a not very secure manner. Here is whan we’d need to do to secure Azure Functions:

Finally, it’d be more secure not to have a key vault, but provide permissions to the managed identity of the Azure Function App.

References:

Microsoft 365 retention policies: Static vs Adaptive scope

Leave a reply

WIP…

Adaptive scopes are good, but what if both policies are implemented? Which one wins?
The scenario for two policies might be: static retention policy is implemented as default retention policy for all sites, and if site require different retention or deletion – it should fall under one of the adaptive scopes and an adaptive retention policy will be applied.

Implementing Microsoft 365 group expiration policy in large companies

2 Replies

This post is dedicated to one specific subject: implementing Microsoft 365 groups lifecycle (expiration) policy in large Microsoft 365 environments.

But this post is also a part of a bigger problem – dealing with ownerless resources in Large Microsoft 365 environments. Please refer to the umbrella post.

Scenario

You administer a large Microsoft 365 environment. Let say you have 100k users or more, 50K or more sites. Environment is not new, so after some years you have a lot of ownerless groups and sites (thousands probably), and a lot of inactive groups and sites (probably tens of thousands). You are getting more and more ownerless groups – hundreds each month. You are thinking of stopping bleeding and cleaning this up…

Implementing Microsoft 365 groups expiration policy

If you are thinking of activating in an existing environment – you would probably have a spike – all the old groups will be subject to policy. The ide is to avoid situation when a specific person – group owner will get dozens of email. It would be better if a person will receieve, let say one email per week.

Here is my 4 possible approaches to avoid this spike, distribute notifications evenly across the time and ease the pain:

By changing Group Lifetime

You would need to change the policy every, e.g. week or month, specifying group lifetime in days starting with maximum period. Consider
– calculate number of days between the oldest group created an today, plus 35 days – it’ll be your first “group lifetime”
– activate the policy with this number of days in “group lifetime” – and within a week you will get notifications on the oldest group/groups
– after a week or two – change the “group lifetime” decreasing it by e.g. 30-60 days and reactivate the policy… and so on

You can easily calculate it all and choose your pace depending on how many groups you have to renew, how much time you need to clean-up. You got the idea.

Downside – in the email notification it will be said “otherwise the group will be deleted on …”, but you joggling with lifetime period – so these dates might confuse users

By renewing groups as admin

As an admin, you can use PowerShell “Reset-PnPMicrosoft365GroupExpiration” or graph API “POST /groups/{id}/renew“ to renew any group.

So depending on total number of groups, number of active/inactive groups, number of ownerless groups in your organization – you can come up with a strategy, using one or more of the following techniques:

  • renew all active and known and important groups (build list of groups to re-activate based on your own criteria) and then trigger the policy
  • build list of definitely inactive groups and renew all other groups
  • split groups into chunks and every day or week (depending on numbers) renew groups in a chunk… after that you can activate groups expiration policy, the policy will be triggered against small number of groups every day/week (with this trick you would avoid policy triggering against large number of groups and sending thousands of emails at one)

By sending customized e-mails to users

Another technique to avoid surge in your e-mail system (and most importantly – avoid sudden influx of support requests) – you can send emails to group owners with a link to renew a group. Surely you’d need to build your custom solution for that, but this does not seem like a complicated task. Some PowerShell scripting – and you are good.

“Renew group” link would look like:
https://account.activedirectory.windowsazure.com/Group/RenewGroup?tenantId=<tenantId>&id=<groupId>
where <tenantId> is tenant id and <groupId> is group Id. So with PowerShell you’d just pull groups in question, their owners and send email with the link dynamically built. Consider spreading this activity across the time to avoid spikes.

By sending users to the groups page

Probably the easies option to smooth the expiration policy implementation is to send group owners to a Microsoft “Groups I own” page – where they could renew or delete their groups. The page is:

Groups I Own (https://myaccount.microsoft.com/groups/groups-i-own)

The downside is – the policy should be in active state (otherwise owners will not see when the group is expiring and option to renew it). So consider a maximum lifetime period in policy, then you’d decrease this period).

Groups expiration policy technical details

Check this KBA for a deep dive into the groups lifecycle policy technical details.

Related content

Microsoft 365 group expiration policy deep dive

9 Replies

Nobody likes garbage, including Microsoft 365 administrators. If any user can create a team or yammer community – they create, but then they leave company and we are getting more and more abandoned groups, teams and SharePoint sites. So we need a way to clean up environment. There is a Microsoft 365 groups expiration policy that can help remove unused groups from the system, but since all Teams and Yammer sites are group-based – it also helps SharePoint admins make things cleaner. In a nutshell what this policy does is it sends notifications to group owners so a group owner can renew the group, otherwise the group will expire and be deleted.

Update (May 2025): Microsoft introduced SharePoint Advanced Management – set of features to help govern SharePoint content for smooth implementation of Copilot. SAM includes Inactive Sites Policy under Site Lifecycle Management. The key differences as I see are: 1) this policy can work not only against group-based sites, but against all sites, including standalone sites. 2) it does not delete sites, but allows to set site to read-only mode and archive. See SharePoint Inactive Site Policies deep dive.

Who can configure the policy and how

The policy lives under Azure Portal, Azure Active Directory, Groups, Expiration:

Microsoft 365 groups expiration policy can be configured by Groups Admin or Global Admin (tenant admin) only. Microsoft 365 Teams or SharePoint admin cannot configure it. Microsoft says that User administrator can do it – so I need to verify it.

Here is the policy config screen:

Microsoft documented it well in the “Microsoft 365 group expiration policy“, but I completed some tests in my lab environment and here is what I found and what is not covered by Microsoft. Let me share it with Questions and Answers format:

Questions and Answers

General questions

Q: How long it takes for policy to start generating notification emails after activation?
A: Immediately, i.e. minutes, maybe up to one hour (in case there groups that are subject for the policy).

Q: Can I customize email that is send to group owners?
A: No, there is no such option at the moment.

Q: What is the email address notifications come from?
A: It’s “msgroupsteam@microsoft.com” with the display name “Microsoft Groups Team”

Q: What does a notification email look like?
A: Please find some examples below, in the end of this article.

Q: Are there other ways to get notifications? Teams?
A: I have not seen any official Microsoft’s documentation on this, but yes – notifications are coming via Teams too: “TeamName is expiring soon. Renew now”:

though it is not clear what exactly should used do to renew the group, as after clicking on that alert a regular teams settings page is opened:

and I got just a few notification in teams, though e-mails notifications I got many.


Q: What happens when a user clicks “Renew group” button in the email notification?
A: User will be sent to a Microsoft’s page and the following “Do you want to renew the group?” window will be shown:

On Yes, it says”<groupName> was successfully renewed. You can close this window now”:

And the group expiration date will be set up as current date.
On “No” it says “Group was not renewed. You can close this window now.”:

And an expiration day will not be changed. No more notifications will be generated. The group will be active until expiration date. Then the group will be deleted.

Q: What if two owners choose opposite?
A: The last action will take effect.

Q: what if one user choose “delete group” but the other one later decided “Renew group”?
A: The one who click “Renew group” will see “<Group Name> successfully renewed. Because the group was deleted, it might take up to 24 hours to be fully restored. You can close this window now.”

Q: What if the group does not have owners?
A: If the group is orphan (ownerless), the expiration emails will go to the email specified in policy configuration. Usually it is a distribution list with admins or other responsible team.

Q: What if the group does have a non-mail-enabled owner?
A: I have tested 2 types of entities with no email:
– just a contact in Outlook
– user with no Exchange license assigned
Results are: Outlook contact cannot be added to team, so there should be no contacts as teams/groups owners; a user with no Exchange licens can be added to team/group and Microsoft does not consider this group ownerless, so notification should be sent to group owners, but since there is no email associated to a group owner – e-mail are not sent, so we are having an issue here.

Q: What if I deactivate the policy – will email notifications sent earlier still be actionable?
In other words, would users still be able to renew the group clicking on the “Renew group” button?
A: Yes. Actually “Renew group” button is just a link to the Url:
https://account.activedirectory.windowsazure.com/Group/RenewGroup?tenantId=<tenantId>&id=<groupId>
where a group owner can renew group.

Q: If one of the owners renewed the group – what will happen with notifications sent to other owner? What if other owner click “Renew group” or “delete group”?
A: Notifications sent will stay. Since buttons in the email are just links (not actionable buttons) – user will be redirected to a web-page where he/she will be able to renew or delete the group.

Q: As per MS: “Groups that are actively in use are renewed automatically around 35 days before the group expires. In this case, the owner does not get any renewal notifications. Any of the following actions will automatically renew a group…<list of actions>”. So, what exactly does “Groups that are actively in use” mean?
A: This is not disclosed by Microsoft. They only say “Azure Active Directory (Azure AD), part of Microsoft Entra, uses intelligence to automatically renew groups based on whether they have been in recent use. This renewal decision is based on user activity in groups across Microsoft 365 services like Outlook, SharePoint, Teams, Yammer, and others.” Btw, <list of actions> includes almost all user actions – so basically any action – even just visit site/team is considered as activity.

Q: Can I track the policy in action via audit log?
A: There is no “activity type” for this policy’s specific actions… You also cannot specify user “msgroupsteam@microsoft.com” to get all activities. So no tracks on the policy “before action” – i.e. at the detection and e-mailing stage.
If a user clicks “renew” button or “delete group” link – this should be logged as this user action with Category “GroupManagement” and activity: “Update group” and “RenewedDateTime” as property modified.
If it happens that the group is deleted by policy – this should be logged under policy’s account – see below.

Automatically renewed group appears as audit log event with
– Workload: AzureActiveDirectory
– RecordType: 8 “AzureActiveDirectory”
– Activity: “Update group”
– Properties modified would be “RenewedDateTime”

Automatically deleted group appears as audit log event with
– Workload: AzureActiveDirectory
– RecordType: 8 “AzureActiveDirectory”
– Activity: “Delete group.”

Microsoft groups lifetime policy operates on behalf of Actor (first-party Microsoft service principal):

  • AppName: Microsoft.ApprovalManagement
  • AppId: 65d91a3d-ab74-42e6-8a2f-0add61688c74
  • Object Id: f64c9eca-18fd-4652-bafe-897fd2d46798

more on first-party Microsoft service principals

Q: After the group is deleted, who can restore it?
A: MS says: “A deleted Microsoft 365 group can be restored within 30 days by a group owner or by an Azure AD administrator”.
In fact, SharePoint admin (and maybe some other roles like Teams admin or Exchange admin) can restore group. SharePoint admin can restore site from recycle bin – and the group will be restored as well.

Q: My org is using retention policies. Will the lifecycle policy delete site if it contradicts with retention policy?
A: Lifecycle policy respects retention policy, so if the site should not be deleted according to retention policy or legal hold – the site will not be deleted (TBC – need to be validated).

Q: What if a user forward this e-mail notification to other user? Can this other user renew or delete the group?
A: When a user receive a notification email forwarded, and he/she click “Renew group” button – his/her experience will be the same if he/she is also a group owner. If a user is not a group owner – he/she will get “You don’t have permission to renew this group because you’re not an owner. To renew , contact a group owner. You can close this window now.”:

Note: if a user with active groups administration permissions receives email and try to renew or delete the group – he/she will also be able to do that.

Q: Can user get information on groups he/her owns, groups expiration data? Can user renew the group before the policy trigger email notification?
A: yes, all that can be done from the page: https://myaccount.microsoft.com/groups/groups-i-own

Q: What if I activate m365 groups lifecycle policy for the selected groups only?
Any insight on policy behavior?
A: The policy will work as usual, but for the selected groups only. Separate from the policy – under “my groups” users will be able to see “Expiration date” and “Renew” option for groups in policy’s scope only:

Scenario with many existing inactive groups

Let say we have a large Microsoft 365 environment with many inactive groups, some of them are inactive for a long time – e.g. 1 or 2 years. We want to implement groups expiration policy, but we want to understand better the policy behavior.

Microsoft says: “The expiration period begins when the group is created, or on the date it was last renewed” and “When you change the expiration policy, the service recalculates the expiration date for each group. It always starts counting from the date when the group was created, and then applies the new expiration policy.”
So in case we implement the policy first time, we know that Renewal Date for all groups is just a Group Creation Date.

See also Strategy of implementing group expiration policy in large Microsoft 365 environments

Q: What will happen if I activate the policy – will the policy start generating emails immediately for all groups?
A: Yes. Once activated – policy starts detecting expired groups and sending notifications to groups owners. So if you have 3k expired groups with 6k owners in it – expect policy will generate 6k e-mail notifications.

Q: Which groups the policy will be triggered against? All or Inactive only?
A: As per Microsoft, if at around 35 days before expiration it will be determined that group is actually active, the policy can renew the group automatically.
But definition of this activity is not disclosed and might be not the same as group activity status 90 days based on MS Graph data you can see at CA.
(I got notifications for groups that were not active recently but with Active status).

Q: In the case above – what would be the deadline? When the policy will delete the group?
A: If the group expiration period is passed, but the policy was just activated – it does not delete the group immediately. Policy allows ~30-35 days for owners to renew the group.
E.g. My test policy was activated May 3 and I got message for old group immediately, but it said that the group will be deleted on June 7.

Q: What if there are more than 10K emails – will it trigger Exchange throttling?
A: Most likely emails not sent will be sent next day.

Q: Can I specify a distribution list in the policy as an “Email contact for groups with no owners”?
A: Yes

Q: Can I specify an external e-mail address as an “Email contact for groups with no owners”?
A: TBC

Q: Can admin ask user to renew or delete the group by some other custom solution (skipping the policy)?
A: yes. Actually, “Renew group” button is just a link to the following Url:
https://account.activedirectory.windowsazure.com/Group/RenewGroup?tenantId=<tenantId>&id=<groupId>
where <tenantId> is tenant id and <groupId> is group Id. So basically anyone

Microsoft 365 Groups object model

Let me explain the policy behavior in m365 group object model terms.

There is a group property “RenewedDateTime”. When group is created – this property is set up to group created date/time (same as group CreatedDateTime property value).
For the notification purposes the policy calculates “Expected Expiration DateTime” as RenewedDateTime plus “Group LifeTime” (number of days specified in policy, e.g. 180). First notification is triggered about 30 days before “Expected Expiration DateTime”, so the policy simply selects groups with RenewedDateTime property value less then current DateTime minus “Group LifeTime days” minus 30 days and sends notification starting from oldest group:

RenewedDateTime < Today - GroupLifeTime -30

When owner confirms group is still needed – RenewedDateTime is setup to current DateTime.

Q: When a user chose to “Renew group” – will it impact group activity?
A: No. If a user did not visit group – but just clicked “Renew group” – it will not trigger group last activity date. E.g. inactive group will still be inactive.

Q: Is there an API to configure Microsoft 365 groups expiration policy programmatically?
A: Yes, in MS Graph API it is called Group Lifecycle Policy: groupLifecyclePolicy. 

Q: Can I programmatically renew the group (all groups) as an admin?
A: Yes, consider using Microsoft Graph API or PowerShell 7 with PnP.PowerShell module.
PnP Doc says Reset-PnPMicrosoft365GroupExpiration command “Renews the Microsoft 365 Group by extending its expiration with the number of days defined in the group expiration policy set on the Azure Active Directory” – but that does not seem accurate. This command sets up “RenewedDateTime” group property to the current datetime, not related to current policy settings (the policy might even not have been activated).
Microsoft Graph API entry point: “POST /groups/{id}/renew“
Group.ReadWrite.All permissions required.

Q: Is it possible to setup “RenewedDateTime” property to another date/time of my choice (not the current date)?
A: Apparently that is not possible. I could not find a way so far… It says
Property 'renewedDateTime' is read-only and cannot be set.

Q: What permissions are required to renew the group with Reset-PnPMicrosoft365GroupExpiration?
A: Group.ReadWrite.All – delegated or application

Q: What exactly is behind the automatic groups renewal?
A: Actually, the is a separate process in parallel with groups expiration policy – and this process starts monitoring groups activity ~35 days before expiration and once activity is detected – the process resets group RenewedDateTime property. And the moment this date is reset – the group is excluded from policy.

Q: If I activate the policy not for all but for a selected groups only, will I still be able to renew other groups programmatically?
A: Yes, as an admin – you can resets group RenewedDateTime property programmatically all alone. It does not matter – whether this policy is activated or not.

Screenshots

Notification e-mail that comes to group owners “as is” – web outlook view:

Notification e-mail that comes to group owners when content is unblocked (web outlook):

Notification e-mail that comes to group owners when pictures are loaded (desktop Outlook):

Notification e-mail that comes to group owners some key areas:

And I’d add that e-mail says how many members in this group (number of members, not including owners… i.e. if you are the only owner – it’ll be zero members).
Correction: “Renew group” is not an actionable button – it is just a html button with a link.

Screenshot of the notification that comes to email specified in policy for the groups that does not have owners:

  • Outlook icon link sends user to group mailbox
  • SharePoint icon is the link to the associated SharePoint site
  • Clicking on Teams icon will transfer user to a default team channel chat page
  • the last one – group icon – is the link to a Microsoft’s groups management page where user can edit group, manage membership, renew group or delete group (see screenshot below):

Renew group button is visible if the expiration policy is activated:

Deleted group

When the not renewed group reaches expiration date – the policy deletes the group and group owners get an e-mail notification like this:

Email subject would be “Attention: <group name> was deleted. Restore it by Thursday, August 10, 2023” and in the body “

<group name> expired on Monday, July 10, 2023. It was deleted, along with all associated communications, files, calendar events, and tasks. You have 30 days from the expiration date to restore Test Priv team – ownerless groups policy and its content. You received this email because you’re an owner of the group”.

Owner can restore group within 30 days by simply clicking “Restore group” button. Then owner would be redirected to the “https://myaccount.microsoft.com/groups/action?groupId=<groupId>&action=Restore” and get a message “The group was successfully restored. It might take up to 24 hours before you can access all associated content. You can close this window now.”

References

Inactive Microsoft 365 groups, teams and SharePoint sites remediation

3 Replies

In Microsoft 365 any users create teams, private/public channels, yammer communities with SharePoint sites behind, as well as standalone SharePoint sites, so in time we – SharePoint engineers – are getting more and more inactive/abandoned groups, teams and SharePoint sites. Dealing with inactive Teams and SharePoint content – as part of Microsoft 365 governance – is a cumbersome, ungrateful and demanding, but necessary and also challenging work, especially in large organizations.

To keep growing content under control – Orgs can use:

In enterprises it’s most likely all of them.

Built-in Microsoft 365 group expiration policy

There is a “Microsoft 365 groups expiration policy” that comes with every tenant and can help remove unused groups from the system, but since all Teams and Yammer sites are group-based – it also helps SharePoint admins make things cleaner.

This policy does a very simple job: on a regular basis it sends notifications to group owners so a group owner can renew the group, otherwise the group will expire and be deleted. Active groups are renewed automatically.

Although it looks simple, there are some tricks and gotchas, so I highly recommend to check this article, especially if you are going to enable the policy in an existing environment.

3-rd party tools

There are many 3-rd party tools on the market that helps with Microsoft 365 administration, information management and governance, e.g. ShareGate, AvePoint, Quest ControlPoint, SysKit Point etc.

Obviously, these 3-rd party tools exist because they can do what Microsoft ootb cannot do or they can do it better then Microsoft. For example

  • Archive teams, SharePoint sites (this is a smart idea, because for instance, a site owner feels like content is not relevant anymore, but cannot take a risk to delete the site – so site owner can choose to archive the site – i.e. keep it for a while but not use it.
  • Delegate tasks to managers or to assigned groups. This is another example of careful attitude to content – e.g. if site owner fails to respond (there might be many reasons) – a tool can reach out to user’s manager or to dedicated resolution group (vs deleting resource blindly) – so somebody can act responsibly and keep the resource or archive or delete it.

Custom solutions – PowerShell scripts, MS Graph API

PowerShell is your best friend when it comes to automation or repeated work or massive updates or ad-hoc reports etc. And PowerShell is your last resort to do something unique, what no other tools can do. PowerShell is very capable and allows to build pretty complex custom solutions.

Microsoft Graph API is a rapidly developing by Microsoft API to manage and work with data in all Microsoft 365 services. You can call MS Graph API from any popular programming language, including PowerShell. Consider Microsoft Graph PowerShell SDK.

PnP – community-based project (not officially supported, but backed by Microsoft). They are doing a really good job providing us with knowledge, guides, tools and SDKs to code against Microsoft 365, including
– Microsoft Graph SDK
– Microsoft Graph Toolkit
– PnP Core SDK
– PnP.PowerShell
– PnPjs

You can use PowerShell to (just a few examples, but there are more scenarios):

  • find and protect resources that you do not want to be a part of policies, but want to deal with manually, on individual basis, e.g.
    – sites or teams owned by top management
    – sites or teams with extremely large content
    – sites or teams with sensitive or other kind of important content
  • implement Microsoft 365 group expiration policy graciously, e.g. step-by-step, via small batches (e.g. updating RenewedDateTime group property would allow you to control when this group will expire and Microsoft start sending notification)
  • deal with non-group-based resources (standalone SharePoint sites), etc.

Solution stack might include VS Code, Microsoft Graph API, Azure Functions, Azure Key Vault, PowerShell, C#, PnP.PowerShell etc.

Microsoft SharePoint Premium (SharePoint Advanced Management)

This is a new, announced in April 2024 and available in 2025 functionality (licensed separately, as Microsoft SharePoint Premium aka SharePoint Advanced Management). Among other benefits, it allows:

Manage site lifecycle policies – an inactive site policy that automatically detects inactive sites and sends notifications to site owners. Sounds familiar? Yes, it resembles the “group expiration policy” but applied to standalone also and there are some more important differences. See my deep dive into SharePoint Inactive Site Policies.

Some more things to consider on the subject

Remediate ownerless SharePoint/Teams resources.

It’s obvious that when you are trying to clean-up inactive resources – you are working with resources owners. Inactive ownerless resource will be simply deleted. That means that before implementing any kind of inactive resources policies – you’d make all efforts to find an owner for every resource to ensure that no important information will be lost in your environment.

I have multiple publications and videos on how to manage ownerless groups in Microsoft 365, including “Deep dive in ownerless Microsoft 365 groups policy“.
Here is the list of orphan Microsoft 365 resources articles.

Retention policies

Though retention policy is something that lives under Purview center (out of SharePoint scope), you should always be aware of it and consider retention configuration, so your settings do not conflict with retention settings.

Microsoft 365 Archive

Again, new functionality. MS says: “Keep your SharePoint content in Microsoft 365 with cost-effective, long-term cold tier storage – without sacrificing manageability, security, and compliance.” In fact, archived sites are no longer accessible by anyone in the organization outside of Microsoft Purview or admin search. Learn more…

Microsoft will be hiding inactive channels.

To keep users channels list relevant, Teams will automatically detect inactive channels user haven’t interacted with in a while, and automatically hide them. Users will have an option to review the list of channels and unhide some or all of them, opt out of automatic hiding from settings, or initiate this process on demand.
Feature ID: 325780