HelpDesk
sign in

SharePoint Online: Microsoft API

Creation date: 4/21/2024 11:23 AM    Updated: 9/18/2024 5:11 PM
Print...
This article provides setup instructions for tracking your SharePoint Online (SPO) environment with the Microsoft API method.

OVERVIEW

  • Angelfish is self-hosted analytics software that creates reports from access logs.
  • Angelfish can download SPO Audit Data and use it to create access logs.
  • This solution uses the SPO Tracking Method, which doesn't use JavaScript.
  • Users can't block themselves from appearing in SPO Audit Data.


NOTES

The access logs created by this solution are compressed (zip format).

SharePoint Audit logs don't contain query parameters: Marketing & Internal Search reports are not available.

Supported API endpoints:
  • Enterprise
  • GCC
  • GCC High Government
  • DoD Government
  • 21Vianet (China)


REQUIREMENTS

  • Angelfish v2.60 or newer
  • Tenant Admin access to your SharePoint Online environment
  • 365 Audit Logging enabled
  • An Angelfish Admin Account

Once you have these, setup should take less than 10 minutes.

TASK SUMMARY

1) In Microsoft Entra, grant API access to Angelfish 
2) In Angelfish, create a Service Account with the API credentials
3) Create a List, Datasource, and Profile


STEP 1: Microsoft Entra 


TASKS

  • Register Angelfish as an Application
  • Create a Client Secret
  • Grant API Permissions to Angelfish

These tasks can performed in Microsoft Entra or in the Azure portal.

Please login to your 365 environment before proceeding:

These tasks also assume Audit Logging is enabled for your organization.

Audit Logging is enabled by default, and you can verify this per the instructions in this article:


Register Angelfish as an Application


In Entra, click "App Registration" in the side menu bar, then "New Registration".  Click the image to zoom in.




In the "Register an application" form, enter a name, choose "Single tenant" for Supported account types, and click the Register button.  Click the image to zoom in.



Copy and save the Application (client) ID and Directory (tenant) ID values - you'll need them in Step 2.

Angelfish is now a registered application.  


Create a Client Secret (passcode)


Click the "Add a certificate or secret" link, then "New client secret"



Enter a description and choose an expiration for the secret.

We recommend making the expiration as long as your organization allows.

When finished, click "Add".

Once saved, the secret is ONLY shown on this screen and will not be shown again.  

The "Value" field contains the secret.  Please copy the Value and save it - you'll need it in Step 2.


Grant API Permissions to Angelfish


Navigate to App registrations - All applications - Angelfish.  See the previous screenshot for reference.

Click "API Permissions" in the side menu, then "Add a permission" in the main body, and click the "Office 365 Management APIs" tile.



Choose "Application permissions", select the "ActivityFeed.Read" permission, and click the "Add permissions" button at the bottom of the screen.

Next, click "Add a permission" and click the "Microsoft Graph" tile.

Two permissions need to be added:
  • Sites.Read.All
  • Users.Read.All

Click "Application permissions".  Navigate to the "Sites" section, expand it, and select Read.All.  



Next, expand Users and select Read.All.  Finally, click the "Add permissions" 

In the main API Permissions screen, click "Grant admin consent for [tenant name]" and choose "Yes" in the confirmation box.



If successful, the API Permissions screen will show a Granted status for each permission.



Congrats!  Your SPO environment is ready for Angelfish to download data!


STEP 2: Create Service Account


A Service Account provides a single location to store authentication credentials, and can be easily updated when passwords change.

Angelfish needs the following info from Step 1 to access your SPO Audit Data:
  • Application (client) ID
  • Directory (tenant) ID
  • Client Secret

Login to Angelfish as an admin, navigate to Accounts - Service Accounts, and click the New button.

In the Service Account Type dropdown menu, select Microsoft API and enter the relevant info in the fields that appear below.




STEP 3: Create List, Datasource, and Profile


Create List


Navigate to the Lists object and click the New button.

Select "Microsoft API" from the List Type menu, then select "Service Account" from the Authentication Type menu and choose the Service Account you created in Step 2.



Click the Test button to make sure the API credentials are valid, then click Next.

Click the Update Now button to download the List, and click Finish.


Create Datasource


Navigate to the Datasources object and click the New button.

Select "SharePoint Online" from the Datasource Type menu, then select "Service Account" from the Authentication Type menu and choose the Service Account you created in Step 2.

Select the correct SharePoint API Endpoint for your organization.

The Location field specifies a local path where logs will be stored once they're downloaded.

The Restrict Content field (not shown in the screenshot) lets you apply a "pre-filter" to data downloaded by this Datasource before the data is saved.  We recommend using this option in environments that have Shared Services teams and multiple content owners.



Click Save when done.


Create Profile


This is the last task!  Now you need to create a new Profile and link it to the Datasource & List.

Navigate to the Profiles object and click the New button - the New Profile Wizard will appear.

NOTES

Use the SharePoint Online Profile Template
In Step 1, add a Clickable Page Prefix
In Step 3, select the Datasource you just created
In Step 4, don't choose any Filters
In Step 5, click Finish - you're not ready to process data yet
Go to the Advanced tab of the Profile and click Show User Analysis Reports
Select the Username List you just created
Go to the Run / Data Management tab and click the Process Data button


If everything is setup correctly, your Angelfish instance will download Audit Data and create reports.  

You can view the progress of the processing job in Task History - click the job row to expand details.

Most new Profiles need some cleanup, which means you should expect to go through a few rounds of "Update and Reprocess" as described here:

Help Articles:
Advanced Info & Tips


DataImage75.png
DataImage64.png
DataImage32.png
DataImage19.png
DataImage60.png
DataImage88.png
DataImage23.png
DataImage80.png
DataImage11.png
DataImage24.png
Files
Sort by Name Sort by Date
Get help for this page Powered by Jitbit HelpDesk