mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-11-09 04:38:49 +00:00
docs(azure): refactor getting started and auth (#8754)
Co-authored-by: Rubén De la Torre Vico <ruben@prowler.com>
This commit is contained in:
Andoni AlonsoandRubén De la Torre Vico authored and GitHub committed
1 parent
48d3fb4fe3
commit
23e1cc281d
4 files changed
+360
-352
No files matched your search
@@ -1,70 +1,229 @@
|
||||
# Azure Authentication in Prowler
|
||||
|
||||
Prowler for Azure supports multiple authentication types. To use a specific method, pass the appropriate flag during execution:
|
||||
Prowler for Azure supports multiple authentication types. Authentication methods vary between Prowler App and Prowler CLI:
|
||||
|
||||
- [**Service Principal Application**](https://learn.microsoft.com/en-us/entra/identity-platform/app-objects-and-service-principals?tabs=browser#service-principal-object) (**Recommended**)
|
||||
- Existing **AZ CLI credentials**
|
||||
- **Interactive browser authentication**
|
||||
- [**Managed Identity**](https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview) authentication
|
||||
**Prowler App:**
|
||||
|
||||
> ⚠️ **Important:** For Prowler App, only Service Principal authentication is supported.
|
||||
- [**Service Principal Application**](#service-principal-application-authentication-recommended)
|
||||
|
||||
### Service Principal Application Authentication
|
||||
**Prowler CLI:**
|
||||
|
||||
Enable Prowler authentication using a Service Principal Application by setting up the following environment variables:
|
||||
- [**Service Principal Application**](#service-principal-application-authentication-recommended) (**Recommended**)
|
||||
- [**AZ CLI credentials**](#az-cli-authentication)
|
||||
- [**Interactive browser authentication**](#browser-authentication)
|
||||
- [**Managed Identity Authentication**](#managed-identity-authentication)
|
||||
|
||||
```console
|
||||
export AZURE_CLIENT_ID="XXXXXXXXX"
|
||||
export AZURE_TENANT_ID="XXXXXXXXX"
|
||||
export AZURE_CLIENT_SECRET="XXXXXXX"
|
||||
```
|
||||
|
||||
Execution with the `--sp-env-auth` flag fails if these variables are not set or exported.
|
||||
|
||||
Refer to the [Create Prowler Service Principal](create-prowler-service-principal.md) guide for detailed setup instructions.
|
||||
|
||||
### Azure Authentication Methods
|
||||
|
||||
Prowler for Azure supports the following authentication methods:
|
||||
|
||||
- **AZ CLI Authentication (`--az-cli-auth`)** – Automated authentication using stored AZ CLI credentials.
|
||||
- **Managed Identity Authentication (`--managed-identity-auth`)** – Automated authentication via Azure Managed Identity.
|
||||
- **Browser Authentication (`--browser-auth`)** – Requires the user to authenticate using the default browser. The `tenant-id` parameter is mandatory for this method.
|
||||
|
||||
### Required Permissions
|
||||
## Required Permissions
|
||||
|
||||
Prowler for Azure requires two types of permission scopes:
|
||||
|
||||
#### Microsoft Entra ID Permissions
|
||||
### Microsoft Entra ID Permissions
|
||||
|
||||
These permissions allow Prowler to retrieve metadata from the assumed identity and perform specific Entra checks. While not mandatory for execution, they enhance functionality.
|
||||
|
||||
Required permissions:
|
||||
#### Assigning Required API Permissions
|
||||
|
||||
Assign the following Microsoft Graph permissions:
|
||||
|
||||
- `Directory.Read.All`
|
||||
- `Policy.Read.All`
|
||||
- `UserAuthenticationMethod.Read.All` (used for Entra multifactor authentication checks)
|
||||
- `UserAuthenticationMethod.Read.All` (optional, for multifactor authentication (MFA) checks)
|
||||
|
||||
???+ note
|
||||
Replace `Directory.Read.All` with `Domain.Read.All` for more restrictive permissions. Note that Entra checks related to DirectoryRoles and GetUsers will not run with this permission.
|
||||
???+ note
|
||||
Replace `Directory.Read.All` with `Domain.Read.All` for more restrictive permissions. Note that Entra checks related to DirectoryRoles and GetUsers will not run with this permission.
|
||||
|
||||
=== "Azure Portal"
|
||||
|
||||
1. Go to your App Registration > "API permissions"
|
||||
|
||||
|
||||
|
||||
2. Click "+ Add a permission" > "Microsoft Graph" > "Application permissions"
|
||||
|
||||
|
||||
|
||||
|
||||
3. Search and select:
|
||||
|
||||
- `Directory.Read.All`
|
||||
- `Policy.Read.All`
|
||||
- `UserAuthenticationMethod.Read.All`
|
||||
|
||||
|
||||
|
||||
4. Click "Add permissions", then grant admin consent
|
||||
|
||||
|
||||
|
||||
=== "Azure CLI"
|
||||
|
||||
1. To grant permissions to a Service Principal, execute the following command in a terminal:
|
||||
|
||||
```console
|
||||
az ad app permission add --id {appId} --api 00000003-0000-0000-c000-000000000000 --api-permissions 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role 246dd0d5-5bd0-4def-940b-0421030a5b68=Role 38d9df27-64da-44fd-b7c5-a6fbac20248f=Role
|
||||
```
|
||||
|
||||
2. Once the permissions are assigned, admin consent is required to finalize the changes. An administrator should run:
|
||||
|
||||
```console
|
||||
az ad app permission admin-consent --id {appId}
|
||||
```
|
||||
|
||||
|
||||
#### Subscription Scope Permissions
|
||||
### Subscription Scope Permissions
|
||||
|
||||
These permissions are required to perform security checks against Azure resources. The following **RBAC roles** must be assigned per subscription to the entity used by Prowler:
|
||||
|
||||
- `Reader` – Grants read-only access to Azure resources.
|
||||
- `ProwlerRole` – A custom role with minimal permissions, defined in the [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json).
|
||||
- `ProwlerRole` – A custom role with minimal permissions needed for some specific checks, defined in the [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json).
|
||||
|
||||
???+ note
|
||||
The `assignableScopes` field in the JSON custom role file must be updated to reflect the correct subscription or management group. Use one of the following formats: `/subscriptions/<subscription-id>` or `/providers/Microsoft.Management/managementGroups/<management-group-id>`.
|
||||
|
||||
### Assigning Permissions
|
||||
#### Assigning "Reader" Role at the Subscription Level
|
||||
By default, Prowler scans all accessible subscriptions. If you need to audit specific subscriptions, you must assign the necessary role `Reader` for each one. For streamlined and less repetitive role assignments in multi-subscription environments, refer to the [following section](subscriptions.md#recommendation-for-managing-multiple-subscriptions).
|
||||
|
||||
To properly configure permissions, follow these guides:
|
||||
=== "Azure Portal"
|
||||
|
||||
1. To grant Prowler access to scan a specific Azure subscription, follow these steps in Azure Portal:
|
||||
Navigate to the subscription you want to audit with Prowler.
|
||||
|
||||
1. In the left menu, select “Access control (IAM)”.
|
||||
|
||||
2. Click “+ Add” and select “Add role assignment”.
|
||||
|
||||
3. In the search bar, enter `Reader`, select it and click “Next”.
|
||||
|
||||
4. In the “Members” tab, click “+ Select members”, then add the accounts to assign this role.
|
||||
|
||||
5. Click “Review + assign” to finalize and apply the role assignment.
|
||||
|
||||
|
||||
|
||||
=== "Azure CLI"
|
||||
|
||||
1. Open a terminal and execute the following command to assign the `Reader` role to the identity that is going to be assumed by Prowler:
|
||||
|
||||
```console
|
||||
az role assignment create --role "Reader" --assignee <user, group, or service principal> --scope /subscriptions/<subscription-id>
|
||||
```
|
||||
|
||||
2. If the command is executed successfully, the output is going to be similar to the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"condition": null,
|
||||
"conditionVersion": null,
|
||||
"createdBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"createdOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00",
|
||||
"delegatedManagedIdentityResourceId": null,
|
||||
"description": null,
|
||||
"id": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleAssignments/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"name": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"principalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"principalName": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"principalType": "ServicePrincipal",
|
||||
"roleDefinitionId": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleDefinitions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"roleDefinitionName": "Reader",
|
||||
"scope": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"type": "Microsoft.Authorization/roleAssignments",
|
||||
"updatedBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"updatedOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00"
|
||||
}
|
||||
```
|
||||
|
||||
#### Assigning "ProwlerRole" Permissions at the Subscription Level
|
||||
|
||||
Some read-only permissions required for specific security checks are not included in the built-in Reader role. To support these checks, Prowler utilizes a custom role, defined in [prowler-azure-custom-role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json). Once created, this role can be assigned following the same process as the `Reader` role.
|
||||
|
||||
The checks requiring this `ProwlerRole` can be found in this [section](../../tutorials/azure/authentication.md#checks-requiring-prowlerrole).
|
||||
|
||||
=== "Azure Portal"
|
||||
|
||||
1. Download the [Prowler Azure Custom Role](https://github.com/prowler-cloud/prowler/blob/master/permissions/prowler-azure-custom-role.json)
|
||||
|
||||
|
||||
|
||||
2. Modify `assignableScopes` to match your Subscription ID (e.g. `/subscriptions/xxxx-xxxx-xxxx-xxxx`)
|
||||
|
||||
3. Go to your Azure Subscription > "Access control (IAM)"
|
||||
|
||||
|
||||
|
||||
4. Click "+ Add" > "Add custom role", choose "Start from JSON" and upload the modified file
|
||||
|
||||
|
||||
|
||||
5. Click "Review + Create" to finish
|
||||
|
||||
|
||||
|
||||
6. Return to "Access control (IAM)" > "+ Add" > "Add role assignment"
|
||||
|
||||
- Assign the `Reader` role to the Application created in the previous step
|
||||
- Then repeat the same process assigning the custom `ProwlerRole`
|
||||
|
||||
|
||||
|
||||
???+ note
|
||||
The `assignableScopes` field in the JSON custom role file must be updated to reflect the correct subscription or management group. Use one of the following formats: `/subscriptions/<subscription-id>` or `/providers/Microsoft.Management/managementGroups/<management-group-id>`.
|
||||
|
||||
=== "Azure CLI"
|
||||
|
||||
1. To create a new custom role, open a terminal and execute the following command:
|
||||
|
||||
```console
|
||||
az role definition create --role-definition '{ 640ms lun 16 dic 17:04:17 2024
|
||||
"Name": "ProwlerRole",
|
||||
"IsCustom": true,
|
||||
"Description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.",
|
||||
"AssignableScopes": [
|
||||
"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // USE YOUR SUBSCRIPTION ID
|
||||
],
|
||||
"Actions": [
|
||||
"Microsoft.Web/sites/host/listkeys/action",
|
||||
"Microsoft.Web/sites/config/list/Action"
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
2. If the command is executed successfully, the output is going to be similar to the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"assignableScopes": [
|
||||
"/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|
||||
],
|
||||
"createdBy": null,
|
||||
"createdOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00",
|
||||
"description": "Role used for checks that require read-only access to Azure resources and are not covered by the Reader role.",
|
||||
"id": "/subscriptions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/providers/Microsoft.Authorization/roleDefinitions/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"name": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"permissions": [
|
||||
{
|
||||
"actions": [
|
||||
"Microsoft.Web/sites/host/listkeys/action",
|
||||
"Microsoft.Web/sites/config/list/Action"
|
||||
],
|
||||
"condition": null,
|
||||
"conditionVersion": null,
|
||||
"dataActions": [],
|
||||
"notActions": [],
|
||||
"notDataActions": []
|
||||
}
|
||||
],
|
||||
"roleName": "ProwlerRole",
|
||||
"roleType": "CustomRole",
|
||||
"type": "Microsoft.Authorization/roleDefinitions",
|
||||
"updatedBy": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
|
||||
"updatedOn": "YYYY-MM-DDTHH:MM:SS.SSSSSS+00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### Additional Resources
|
||||
|
||||
For more detailed guidance on subscription management and permissions:
|
||||
|
||||
- [Microsoft Entra ID permissions](create-prowler-service-principal.md#assigning-proper-permissions)
|
||||
- [Azure subscription permissions](subscriptions.md)
|
||||
- [Create Prowler Service Principal](create-prowler-service-principal.md)
|
||||
|
||||
???+ warning
|
||||
Some permissions in `ProwlerRole` involve **write access**. If a `ReadOnly` lock is attached to certain resources, you may encounter errors, and findings for those checks will not be available.
|
||||
@@ -75,3 +234,56 @@ The following security checks require the `ProwlerRole` permissions for executio
|
||||
|
||||
- `app_function_access_keys_configured`
|
||||
- `app_function_ftps_deployment_disabled`
|
||||
|
||||
---
|
||||
|
||||
## Service Principal Application Authentication (Recommended)
|
||||
|
||||
This method is required for Prowler App and recommended for Prowler CLI.
|
||||
|
||||
### Creating the Service Principal
|
||||
For more information, see [Creating Prowler Service Principal](create-prowler-service-principal.md).
|
||||
|
||||
### Environment Variables (CLI)
|
||||
|
||||
For Prowler CLI, set up the following environment variables:
|
||||
|
||||
```console
|
||||
export AZURE_CLIENT_ID="XXXXXXXXX"
|
||||
export AZURE_TENANT_ID="XXXXXXXXX"
|
||||
export AZURE_CLIENT_SECRET="XXXXXXX"
|
||||
```
|
||||
|
||||
Execution with the `--sp-env-auth` flag fails if these variables are not set or exported.
|
||||
|
||||
## AZ CLI Authentication
|
||||
|
||||
*Available only for Prowler CLI*
|
||||
|
||||
Use stored Azure CLI credentials:
|
||||
|
||||
```console
|
||||
prowler azure --az-cli-auth
|
||||
```
|
||||
|
||||
## Managed Identity Authentication
|
||||
|
||||
*Available only for Prowler CLI*
|
||||
|
||||
Authenticate via Azure Managed Identity (when running on Azure resources):
|
||||
|
||||
```console
|
||||
prowler azure --managed-identity-auth
|
||||
```
|
||||
|
||||
## Browser Authentication
|
||||
|
||||
*Available only for Prowler CLI*
|
||||
|
||||
Authenticate using the default browser:
|
||||
|
||||
```console
|
||||
prowler azure --browser-auth --tenant-id <tenant-id>
|
||||
```
|
||||
|
||||
> **Note:** The `tenant-id` parameter is mandatory for browser authentication.
|
||||
Reference in new issue
Block a user