IDECSI / O365 API Permissions

Preamble

The API permissions, in O365, are grouped by resource. A resource can be seen as the web services hosted in O365 used to retrieve the information.

All permissions must be “Application”, they cannot be “Delegate”. We apply the Microsoft recommendations for our usage.
Why we need it: This type of permission affects how we get the token for requests. In “Delegate” mode, it would prevent us from running in background.

As a reminder, IDECSI can work with different levels of permissions:

1. Classic:
   IDECSI with this level can perform full efficient behavior & access detection and get the details on previous permissions granted on SP / OD.
   This permission level cannot perform auto-remediation.
   This permission level technically allows the application’s owner to read the content of the files.
   
2. Remediation:
   This level includes the Classic level permissions and includes additional write rights on SP / OD allowing the solution to perform remediation on users and permissions on SP / OD.
   This permission level technically allows the application’s owner to write/delete the content of the files.

Notes

The application owner can either be IDECSI’s O365 tenant or any other tenant declared in Azure AD.

Credentials can be ‘dispatched’ in different applications (for ex. IDECSI’s app for the classic level of permissions, a tenant-specific app for the Remediation level of permissions).

In such case, and with an On-Premise LEM acting as a collect agent, IDECSI does not require to be informed of the Remediation credentials. It will be stored cyphered locally on the LEM.

Grant of the IDECSI application

Idecsi provides 2 applications; one for each permission level.

The app can be granted simply by clicking one of the following links:

Classic

https://login.microsoftonline.com/common/adminConsent?client_id=8d61a8fa-7d39-46d8-8a3f-509a9941db81

Remediation

https://login.microsoftonline.com/common/adminConsent?client_id=0f0db085-0c7b-409a-9e7e-d1130282ea65

Permissions details

Scope

EXC: Exchange – AAD: Azure AD – OD: OneDrive – SP: SharePoint

All permissions must be “Application”, they cannot be “Delegate”. We apply the Microsoft recommendations for our usage.
Why we need it: This type of permission affects how we get the token for requests. In “Delegate” mode, it would prevent us from running in background.

Classic permissions level

Microsoft Graph

This API is used to read information on Office 365 and Azure AD items.

• AuditLog.Read.All (AAD)

Allows the app to read and query your audit log activities, without a signed-in user.

Why we need it: Used to read Azure AD Sign-in logs (Office 365 Unified Audit Logs are not granted by this permission)

• Directory.Read.All (EXC, AAD, OD, SP)

Why we need it: Used to read data in your organization’s directory, such as users, groups and apps, without a signed-in user.

• Files.Read.All (OD, SP)

Allows the app to read all files in all site collections without a signed-in user. Used to read the metadata and the permissions of Files.

Why we need it: In the API there’s no distinction between “I want to read the metadata” and “I want to read the file”. Of course, we don’t access the content of files, we only read the metadata (name, dates, AIP classification, versioning, …), browse the file tree, and get the permissions on the files/folder.

• Group.Read.All (OD, SP)

Allows the app to read group properties and memberships, and read conversations for all groups, without a signed-in user.

Why we need it: Used to detect the nature of sharepoint resources : Yammer, Teams, etc

• IdentityProvider.Read.All

Allows the app to read your organization’s identity (authentication) providers’ properties without a signed-in user.

Why we need it: Will be used to read the properties of Identity Providers and to investigate in case of suspicious action

• InformationProtectionPolicy.Read.All (EXC, AAD, OD, SP)

Allows an app to read published sensitivity labels and label policy settings for the entire organization or a specific user, without a signed-in user.

Why we need it: Used to read Microsoft Information Protection Sensitivity labels

• MailboxSettings.Read (EXC)

Why we need it: Used to read user’s mailbox settings without a signed-in user. Does not include permission to send mail.

• Member.Read.Hidden (EXC, AAD, OD, SP)

Allows the app to read the memberships of hidden groups and administrative units without a signed-in user.

Why we need it: Used to read hidden groups memberships. Note: This permission is required in addition to Directory.Read.All

• Policy.Read.All (EXC, AAD, OD, SP)

Allows the app to read all your organization’s policies without a signed-in user.

Why we need it: Will be used to analyze the organization policies (e.g. Conditional Access)

• Reports.Read.All (OD, SP)

Allows an app to read all service usage reports without a signed-in user. Services that provide usage reports include Office 365 and Azure Active Directory.

Why we need it: This gives us the stats (number of files, space used, …) we need to evaluate and measure the data collections on OD/SP.

• Sites.Read.All (OD, SP)

Allows the app to read documents and list items in all site collections without a signed-in user.

Why we need it: Used to read the SharePoint sites structure, files properties and permissions. Note: In the API there’s no distinction between “I want to read the metadata” and “I want to read the file”. Of course, we don’t access the content of files, we only read the metadata (name, dates, AIP classification, versioning, …), browse the files tree, and get the permissions on the files/folder.

• ThreatAssessment.Read.All

Why we need it: Used to read your organization’s threat assessment requests (Secure Score), without a signed-in user.

• ThreatIndicators.Read.All

Why we need it: Used to read all the indicators for your organization, without a signed-in user. Will be used to read Defender alerts.

• UserAuthenticationMethod.Read.All

Allows the app to read authentication methods of all users in your organization, without a signed-in user. Authentication methods include things like a user’s phone numbers and Authenticator app settings. This does not allow the app to see secret information like passwords, or to sign-in or otherwise use the authentication methods.

Why we need it:Will be used to read Authentication Methods (e.g. to display them in MyDataSecurity)

Office 365 Management APIs

• ActivityFeed.Read (EXC, AAD, OD, SP)

Allows the application to read activity data for your organization.

Why we need it: Used to read Office 365 Unified Audit Logs

• ActivityFeed.ReadDlp (EXC, AAD, OD, SP)

Why we need it: Will be used to read DLP alerts and auto-classification

Remediation permissions level

The remediation permissions level requires the classic permissions level plus the following permissions

Microsoft Graph

• Files.ReadWrite.All (OD, SP)

Allows the app to read, create, update and delete all files in all site collections without a signed-in user.

Why we need it: Used to update files permissions

• Group.ReadWrite.All (OD, SP)

Allows the app to create groups, read all group properties and memberships, update group properties and memberships, and delete groups. Also allow the app to read and write group calendar and conversations. All of these operations can performed by the app without a signed-in user.

Why we need it: Used to update groups memberships

• Sites.ReadWrite.All (OD, SP)

Allows the app to create, read, update, and delete documents and list items in all site collections without a signed-in user.

Why we need it: Used to update files and lists items permissions (but not SharePoint permissions)

• User.ReadWrite.All (EXC, AAD, OD, SP)

Allows the app to read and update user profiles without a signed-in user.

Why we need it: Used to update user status

SharePoint API – CSOM

SharePoint API – CSOM rights are required to have a full view of a SharePoint site structure and permissions.

• Sites.FullControl.All (OD, SP)

Allows the app to have full control of all site collections without a signed-in user.

Why we need it: Used to read and modify any direct permissions on SharePoint site collections, sites, lists, libraries or items.

Create an app

Preamble

This section quickly describes how to create an app with API Permissions.

For complete documentation on Azure AD App Registrations, API Permissions, Scopes, … please refer to Microsoft documentation.

Below are some useful links:

• https://docs.microsoft.com/en-us/graph/auth-register-app-v2
• https://docs.microsoft.com/en-us/graph/auth-v2-service
• https://docs.microsoft.com/en-us/graph/permissions-reference
• https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis

App creation

1. Sign on to the Azure portal (https://portal.azure.com/#home) with tenant administration privileges.
2. Go to the “Azure Active Directory” service
3. In the service details menu bar, choose “App Registrations”, and start a “New registration”
4. Fill in the name and click Register
5. In the app details menu bar, choose “API Permissions”, then “Add a permission”
6. Add the permissions listed in the next sections

App Authentication

The first step is to create a certificate; from a custom authority, or by creating a self-signed certificate.

Below this one way of generating a self-signed certificate :

# --- configuration
$password = "ID12345!" # Certificate password
$folderPath = "C:\Certificate" # Where do you want the files to get saved to? The folder needs to exist.
$fileName = "I2A_Certificate" # What do you want to call the cert files? without the file extension
$yearsValid = 1 # Number of years until you need to renew the certificate

# --- 
$certStoreLocation = "cert:\CurrentUser\My"
$expirationDate = (Get-Date).AddYears($yearsValid)

$certificate = New-SelfSignedCertificate -Subject "CN=I2A App Authentication" -CertStoreLocation $certStoreLocation -NotAfter $expirationDate -KeyExportPolicy Exportable -KeySpec Signature

$certificatePath = $certStoreLocation + '\' + $certificate.Thumbprint
$filePath = $folderPath + '\' + $fileName
$securePassword = ConvertTo-SecureString -String $password -Force -AsPlainText

Export-Certificate -Cert $certificatePath -FilePath ($filePath + '.cer')
Export-PfxCertificate -Cert $certificatePath -FilePath ($filePath + '.pfx') -Password $securePassword

After this procedure, there are two files:

1. A .cer file containing the public key of the certificate
2. A .pfx file containing the public AND private key of the certificate (secured by the password defined)

The certificate can now be used in the Azure Portal :

1. In the app details menu bar, choose “Certificates & secrets”, then “Upload certificate”
2. Upload the .cer file
3. As result, there’s a thumbprint displayed with the date details of the certificate

If the DataCollect / Remediation is done by IDECSI’s cloud, please transmit securely the certificate and the certificate password to IDECSI’s support.

If the DataCollect / Remediation is done On-Premise by a LEM, please add the certificate in the local store of the service account used to run the “I2A Worker” service and transmit the thumbprint of the certificate to IDECSI’s support.