How to Create and Use a SharePoint App Registration

SharePoint App Registrations are incredibly useful for unattended tasks to read or update SharePoint sites. It's similar to a user service account but more secure. They cannot be used as a user sign-in. They are used in custom applications or automated scripted processes. They are made even more secure with a certificate, in which case, they may only run from the machine that owns the certificate.

SharePoint Things to Do with App Registrations

• Read data and write the data to another process
• Write CSV, text, or XML files
• Useful for data for to import into report software
• Writing the data to other APIs such as ERPs, Project software, or work authorization systems
• Changing the data
• Check the data based on a schedule. Update the data based on constraints
• Change permissions of items in a SharePoint list once an item is past due
• Work with partners and vendors to provide just-in-time, specific access to necessary data

Simple Process

1. Create the application either in SharePoint or in App Registrations of portal.azure.com
2. Grant the app registration permission to the SharePoint resource using the appinv.aspx SharePoint API
3. Scope the app registration to the site using Read, Write, Manage, or Full Control
4. Verify the access

Detailed Process

Generate the App Registration

App Registrations Can Be Created in Two Different Ways

1. App Registration can be created in the Azure App Registrations App registrations - Microsoft Azure. Click new registration. (I prefer this way because now all my app registrations can be centrally managed, and it provides greater detail to me and other administrators.)
2. SharePoint Site for creating the app: https://<tenant>.sharepoint.com/_layouts/15/appregnew.aspx. (This is the old way that works with on-prem SharePoint servers too.)
3. Store the client ID and Client Secret. The Client Secret cannot be retrieved after this screen and will be lost once you navigate away. Another benefit of the Azure Portal App Registration method is you can easily create a new Client Secret if you mess up or forget this step.

Grant Access within the Admin Center

1. Lookup using the previously created Client ID. 
1. If you used the Azure Portal, this can easily be found in the list of App Registrations.
2. If you used the SharePoint "appregnew.aspx" web page, be sure to copy the ID.
3. Go to https://<tenant>-admin.sharepoint.com/_layouts/15/appinv.aspx and paste the App Registration ID into the App ID box and click Lookup.
   
   
   
   
   
4. The app domain and redirect URL are not important and can be any value, but I like to put the site collection for which I am giving the app permission into the redirect URL. It has no effect on permissions. It is just more information that helps me remind myself what site the app is for.

Scoping the Permissions - Permission Request XML schema

This is the part that makes the app registration work. You can copy and paste the example and change the Scope and the Right. I highlight AllowAppOnlyPolicy, Scope URI, and Right because each one impacts how your app registration functions. If you forget the AllowAppOnlyPolicy="true", the app registration will give you a 403 error. The scope URI indicates at what level the right is applied. Do you want to grant access to the entire tenant (including all sites), just one site, or maybe just one list on the site. This is a really important decision to make to ensure you grant the app least privilege.

The XML Schema:

<AppPermissionRequests  AllowAppOnlyPolicy="true"> 
<AppPermissionRequest Scope="<Scope URI>"  Right="<Right>" /> 
</AppPermissionRequests> 

A Working Example:

<AppPermissionRequests   AllowAppOnlyPolicy="true>

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

</AppPermissionRequests> 

Possible Values of Scope URI from Most Permissions to Least Permissions

• http://sharepoint/content/tenant – Permissions are granted to the Add-in at tenant level. Tenant level permissions are granted when tenant level operations need to perform like creating a site collection etc. or performing the operations across different Site Collections.
• http://sharepoint/content/sitecollection – Permissions are granted to the Add-in at one Site Collection level.
• http://sharepoint/content/sitecollection/web– Permissions are granted to the Add-in at one web level.
• http://sharepoint/content/sitecollection/web/list – Permissions are granted to the Add-in at one list level.

Possible Values of Right from Least Permissions to Most Permissions

Right: Rights given Add-in. SharePoint supports four right levels:

• Read - only read information
• Write - Update information, create new items
• Manage - More than write, you can also alter permissions
• FullControl - create lists, document libraries, manage the site and delete content

Verify

How to View Apps on a Site

Examples:

• At the tenant: https://<tenant>-admin.sharepoint.com/_layouts/15/AppPrincipals.aspx
• At a site: https://<tenant>.sharepoint.com/sites/<site_name>/_layouts/15/AppPrincipals.aspx
  

How to Verify It's Working

1. Using Connect-PnPOnline -url <your_url> -ClientID <your_app_registration_id> -clientsecret <your_client_secret> lets you know if you created and trusted your app registration correctly
2. Get-PnPSite or Get-PnPList will confirm if you scoped your access correctly.
1. Sometimes you can connect to the site but can't read anything on the site because your scope wasn't set correctly.
3. Once it is working, you can also use PowerShell cmdlets such as Invoke-RestMethod to access SharePoint APIS or use tools like Postman to access the site as well.

References

• 3rd Party Reference: Office 365: SharePoint Online – Assigning Permissions to SharePoint Add-In | Knowledge Junction (knowledge-junction.com) 
• Microsoft Reference: Add-in permissions in SharePoint | Microsoft Docs 
• Microsoft Reference: https://docs.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs
• Reference: sharepoint online - How can I view a list of applications added by AppRegNew.aspx? - SharePoint Stack Exchange 
• Connect-PnPOnline | PnP PowerShell

1.