feat(m365powershell): add pwsh authentication via service principal (#7992)

Co-authored-by: alejandrobailo <alejandrobailo94@gmail.com>
Co-authored-by: Adrián Jesús Peña Rodríguez <adrianjpr@gmail.com>
Co-authored-by: Daniel Barranquero <danielbo2001@gmail.com>
Co-authored-by: MrCloudSec <hello@mistercloudsec.com>

docs/getting-started/requirements.md

@@ -139,7 +139,7 @@ Prowler for M365 currently supports the following authentication types:
 ???+ warning
     For Prowler App only the Service Principal with User Credentials authentication method is supported.
 
-### Service Principal authentication
+### Service Principal authentication (recommended)
 
 Authentication flag: `--sp-env-auth`
 
@@ -154,9 +154,11 @@ export AZURE_TENANT_ID="XXXXXXXXX"
 If you try to execute Prowler with the `--sp-env-auth` flag and those variables are empty or not exported, the execution is going to fail.
 Follow the instructions in the [Create Prowler Service Principal](../tutorials/microsoft365/getting-started-m365.md#create-the-service-principal-app) section to create a service principal.
 
-With this credentials you will only be able to run the checks that work through MS Graph, this means that you won't run all the provider. If you want to scan all the checks from M365 you will need to use the recommended authentication method.
+If you don't add the external API permissions described in the mentioned section above you will only be able to run the checks that work through MS Graph. This means that you won't run all the provider.
 
-### Service Principal and User Credentials authentication (recommended)
+If you want to scan all the checks from M365 you will need to use the recommended authentication method or add the external API permissions.
+
+### Service Principal and User Credentials authentication
 
 Authentication flag: `--env-auth`
 
@@ -213,6 +215,8 @@ Prowler for M365 requires two types of permission scopes to be set (if you want
     - `Policy.Read.All`: Required for all services.
     - `SharePointTenantSettings.Read.All`: Required for SharePoint service.
     - `User.Read` (IMPORTANT: this must be set as **delegated**): Required for the sign-in.
+    - `Exchange.ManageAsApp` from external API `Office 365 Exchange Online`: Required for Exchange PowerShell module app authentication. You also need to assign the `Exchange Administrator` role to the app.
+    - `application_access` from external API `Skype and Teams Tenant Admin API`: Required for Teams PowerShell module app authentication.
 
     ???+ note
         You can replace `Directory.Read.All` with `Domain.Read.All` is a more restrictive permission but you won't be able to run the Entra checks related with DirectoryRoles and GetUsers.
@@ -221,7 +225,8 @@ Prowler for M365 requires two types of permission scopes to be set (if you want
 
 
 
-- **Powershell Modules Permissions**: These are set at the `M365_USER` level, so the user used to run Prowler must have one of the following roles:
+
+- **Powershell Modules Permissions** (if using user credentials): These are set at the `M365_USER` level, so the user used to run Prowler must have one of the following roles:
     - `Global Reader` (recommended): this allows you to read all roles needed.
     - `Exchange Administrator` and `Teams Administrator`: user needs both roles but with this [roles](https://learn.microsoft.com/en-us/exchange/permissions-exo/permissions-exo#microsoft-365-permissions-in-exchange-online) you can access to the same information as a Global Reader (since only read access is needed, Global Reader is recommended).
 
@@ -439,6 +444,7 @@ The required modules are:
 
 - [ExchangeOnlineManagement](https://www.powershellgallery.com/packages/ExchangeOnlineManagement/3.6.0): Minimum version 3.6.0. Required for several checks across Exchange, Defender, and Purview.
 - [MicrosoftTeams](https://www.powershellgallery.com/packages/MicrosoftTeams/6.6.0): Minimum version 6.6.0. Required for all Teams checks.
+- [MSAL.PS](https://www.powershellgallery.com/packages/MSAL.PS/4.32.0): Required for Exchange module via application authentication.
 
 ## GitHub
 ### Authentication

docs/index.md

@@ -572,12 +572,12 @@ With M365 you need to specify which auth method is going to be used:
 
 ```console
 
+# To use service principal authentication for MSGraph and PowerShell modules
+prowler m365 --sp-env-auth
+
 # To use both service principal (for MSGraph) and user credentials (for PowerShell modules)
 prowler m365 --env-auth
 
-# To use service principal authentication
-prowler m365 --sp-env-auth
-
 # To use az cli authentication
 prowler m365 --az-cli-auth
 

docs/tutorials/microsoft365/getting-started-m365.md

@@ -92,7 +92,7 @@ With this done you will have all the needed keys, summarized in the following ta
 
 ---
 
-### Grant required API permissions
+### Grant required Graph API permissions
 
 Assign the following Microsoft Graph permissions:
 
@@ -100,7 +100,7 @@ Assign the following Microsoft Graph permissions:
 - `Directory.Read.All`: Required for all services.
 - `Policy.Read.All`: Required for all services.
 - `SharePointTenantSettings.Read.All`: Required for SharePoint service.
-- `User.Read` (IMPORTANT: this is set as **delegated**): Required for the sign-in.
+- `User.Read` (IMPORTANT: this is set as **delegated**): Required for the sign-in only if using user authentication.
 
 ???+ note
     You can replace `Directory.Read.All` with `Domain.Read.All` is a more restrictive permission but you won't be able to run the Entra checks related with DirectoryRoles and GetUsers.
@@ -128,18 +128,83 @@ Follow these steps to assign the permissions:
 
     ![Application Permissions](./img/app-permissions.png)
 
+---
 
-4. Click `+ Add a permission` > `Microsoft Graph` > `Delegated permissions`
 
-    ![Add API Permission](./img/add-delegated-api-permission.png)
+### Grant PowerShell modules permissions
 
-5. Search and select:
+The permissions you need to grant depends on whether you are using user credentials or service principal to authenticate to the M365 modules.
+
+???+ warning "Warning"
+    Make sure you add the correct set of permissions for the authentication method you are using.
+
+
+#### If using application(service principal) authentication
+
+???+ warning "Warning"
+    Currently Prowler Cloud only supports user authentication.
+
+To grant the permissions for the PowerShell modules via application authentication, you need to add the necessary APIs to your app registration.
+
+???+ warning "Warning"
+    You need to have a license that allows you to use the APIs.
+
+1. Add Exchange API:
+
+    - Search and select`Office 365 Exchange Online` API in **APIs my organization uses**.
+
+    ![Office 365 Exchange Online API](./img/search-exchange-api.png)
+
+    - Select `Exchange.ManageAsApp` permission and click on `Add permissions`.
+
+    ![Exchange.ManageAsApp Permission](./img/exchange-permission.png)
+
+    You also need to assign the `Exchange Administrator` role to the app. For that go to `Roles and administrators` and in the `Administrative roles` section click `here` to go to the directory level assignment:
+
+    ![Roles and administrators](./img/here.png)
+
+    Once in the directory level assignment, search for `Exchange Administrator` and click on it to open the assginments page of that role.
+
+    ![Exchange Administrator Role](./img/exchange-administrator-role.png)
+
+    Click on `Add assignments`, search for your app and click on `Assign`.
+
+    You have to select it as `Active` and click on `Assign` to assign the role to the app.
+
+    ![Assign Exchange Administrator Role](./img/assign-exchange-administrator-role.png)
+
+2. Add Teams API:
+
+    - Search and select `Skype and Teams Tenant Admin API` API in **APIs my organization uses**.
+
+    ![Skype and Teams Tenant Admin API](./img/search-skype-teams-tenant-admin-api.png)
+
+    - Select `application_access` permission and click on `Add permissions`.
+
+    ![application_access Permission](./img/teams-permission.png)
+
+3. Click on `Grant admin consent for <your-tenant-name>` to grant admin consent.
+
+    ![Grant Admin Consent](./img/grant-external-api-permissions.png)
+
+    The final result of permission assignment should be this:
+
+    ![Final Permission Assignment](./img/final-permissions.png)
+
+???+ warning
+    Remember that if the user is newly created, you need to sign in with that account first, as Microsoft will prompt you to change the password. If you don’t complete this step, user authentication will fail because Microsoft marks the initial password as expired.
+
+---
+
+#### If using user authentication (Currently Prowler Cloud only supports this method)
+
+1. Search and select:
 
     - `User.Read`
 
     ![Permission Screenshots](./img/directory-permission-delegated.png)
 
-6. After adding all the permissions, click on `Grant admin consent`
+2. Click `Add permissions`, then **grant admin consent**
 
     ![Grant Admin Consent](./img/grant-admin-consent.png)
 
@@ -147,37 +212,32 @@ Follow these steps to assign the permissions:
 
     ![Final Permission Assignment](./img/final-permissions-m365.png)
 
----
+3. Assign **required roles** to your **user**
 
-### Assign required roles to your user
+    Assign one of the following roles to your User:
 
-Assign one of the following roles to your User:
+    - `Global Reader` (recommended): this allows you to read all roles needed.
+    - `Exchange Administrator` and `Teams Administrator`: user needs both roles but with this [roles](https://learn.microsoft.com/en-us/exchange/permissions-exo/permissions-exo#microsoft-365-permissions-in-exchange-online) you can access to the same information as a Global Reader (here you only read so that's why we recomend that role).
 
-- `Global Reader` (recommended): this allows you to read all roles needed.
-- `Exchange Administrator` and `Teams Administrator`: user needs both roles but with this [roles](https://learn.microsoft.com/en-us/exchange/permissions-exo/permissions-exo#microsoft-365-permissions-in-exchange-online) you can access to the same information as a Global Reader (here you only read so that's why we recomend that role).
+    Follow these steps to assign the role:
 
-Follow these steps to assign the role:
+    1. Go to Users > All Users > Click on the email for the user you will use
 
-1. Go to Users > All Users > Click on the email for the user you will use
+        ![User Overview](./img/user-info-page.png)
 
-    ![User Overview](./img/user-info-page.png)
+    2. Click `Assigned Roles`
 
-2. Click `Assigned Roles`
+        ![User Roles](./img/user-role-page.png)
 
-    ![User Roles](./img/user-role-page.png)
+    3. Click on `Add assignments`, then search and select:
 
-3. Click on `Add assignments`, then search and select:
+        - `Global Reader` This is the recommended, if you want to use the others just search for them
 
-    - `Global Reader` This is the recommended, if you want to use the others just search for them
+        ![Global Reader Screenshots](./img/global-reader.png)
 
-    ![Global Reader Screenshots](./img/global-reader.png)
+    4. Click on next, then assign the role as `Active`, and click on `Assign` to grant admin consent
 
-4. Click on next, then assign the role as `Active`, and click on `Assign` to grant admin consent
-
-    ![Grant Admin Consent for Role](./img/grant-admin-consent-for-role.png)
-
-???+ warning
-    Remember that if the user is newly created, you need to sign in with that account first, as Microsoft will prompt you to change the password. If you don’t complete this step, user authentication will fail because Microsoft marks the initial password as expired.
+        ![Grant Admin Consent for Role](./img/grant-admin-consent-for-role.png)
 
 ---