SAML Single Sign-On (SSO)

• User Guide: For organization administrators to configure SAML SSO through Prowler Cloud.
• Developer and Administrator Guide: For developers and system administrators running Prowler Local Server instances, providing technical details on environment configuration, API usage, and testing.

​

User Guide Configuration

​

Key Features

• IdP-Initiated SSO: Users can initiate login from their Identity Provider’s dashboard.
• SP-Initiated SSO: Users can initiate login directly from the Prowler login page.
• Just-in-Time Provisioning: Users from the organization signing into Prowler for the first time will be automatically created.

​

Prerequisites

• Administrator access to the Prowler organization is required.
• Administrative access to the SAML 2.0 compliant Identity Provider (e.g., Okta, Azure AD, Google Workspace) is necessary.

​

Configuration Steps

​

Step 1: Access Profile Settings

​

Step 2: Enable SAML Integration

​

Step 3: Configure the Identity Provider (IdP)

• Use Generic Method for any SAML 2.0 compliant Identity Provider or when you need custom configuration.
• Use Okta App Catalog if you’re using Okta and want a simplified setup process with pre-configured settings.

• Generic Method
• Okta App Catalog

Prowler Cloud displays the SAML configuration information needed to configure the IdP. Use this information to create a new SAML application in the IdP.

1. Assertion Consumer Service (ACS) URL: The endpoint in Prowler that will receive the SAML assertion from the IdP.
2. Audience URI (Entity ID): A unique identifier for the Prowler application (Service Provider).

To configure the IdP, copy the ACS URL and Audience URI from Prowler Cloud and use them to set up a new SAML application.

IdP ConfigurationThe exact steps for configuring an IdP vary depending on the provider (Okta, Azure AD, Google Workspace, etc.). Please refer to the IdP’s documentation for instructions on creating a SAML application. For SSO integration with Azure AD / Entra ID, see our Entra ID configuration instructions. For Google Workspace, see our Google Workspace configuration instructions.

Configure Attribute Mapping in the IdPFor Prowler Cloud to correctly identify and provision users, configure the IdP to send the following attributes in the SAML assertion:

Attribute Name	Description	Required
firstName	The user’s first name.	Yes
lastName	The user’s last name.	Yes
userType	Determines which Prowler role the user receives (e.g., admin, auditor). If a role with that name already exists, the user receives it automatically; if it does not exist, Prowler Cloud creates a new role with that name with read-only access (visibility over all providers, no management permissions). A Prowler administrator can adjust its permissions through the RBAC Management tab. If userType is not defined, Prowler Cloud applies the fallback behavior described below.	No
organization	The user’s company name.	No

Fallback Role Without userTypeIf userType is not defined, the user’s existing roles are left unchanged. Users without an existing role in that tenant receive a least-privilege read_only fallback role. If read_only already belongs to a role with different permissions, Prowler Cloud checks suffixed names in order, starting with read_only_0. It reuses the first role with the fallback permissions or creates the first available name. A Prowler administrator can then assign the appropriate role through the RBAC Management tab.

IdP Attribute MappingNote that the attribute name is just an example and may be different depending on the IdP. For instance, if the IdP provides a division attribute, it can be mapped to userType.

Single-Value userType RequiredMap userType to an IdP attribute that always contains a single value. If the IdP sends multiple values, Prowler Cloud uses only the first value and does not assign multiple roles or select the highest-privilege role.

Dynamic UpdatesProwler Cloud updates these attributes each time a user logs in. Any changes made in the Identity Provider (IdP) will be reflected when the user logs in again.

Instead of creating a custom SAML integration, Okta administrators can configure Prowler Cloud directly from Okta’s application catalog.You can find a walkthrough video here.

1. Access App Catalog: Navigate to the IdP’s application catalog (e.g., Browse App Catalog in Okta).
2. Search for Prowler Cloud: Use the search functionality to find “Prowler Cloud” in the app catalog. The official Prowler Cloud application will appear in the search results.
3. Select Prowler Cloud Application: Click the Prowler Cloud application from the search results to view its details page.
4. Add Integration: Click the “Add Integration” button to begin adding Prowler Cloud to the organization’s applications.
5. Configure General Settings: In the “Add Prowler Cloud” configuration screen, the integration automatically configures the necessary settings.
6. Assign Users: Navigate to the “Assignments” tab and assign the appropriate users or groups to the Prowler application by clicking “Assign” and selecting “Assign to People” or “Assign to Groups”.
7. Configure User Attributes in Okta: Okta acts as the central source for user profile information. Prowler Cloud maps the following Okta user profile attributes during each SAML login:
   • First name (firstName): Maps to the user’s first name in Prowler Cloud.
   • Last name (lastName): Maps to the user’s last name in Prowler Cloud.
   
   • Organization (organization): Maps to the company name displayed in Prowler Cloud. This attribute is optional.
   • User type (userType): Determines the Prowler role assigned to the user. This attribute is case-sensitive: if it matches the exact name of an existing role in Prowler Cloud the user receives that role; if no role with that name exists, a new one is created with read-only access.
   To modify these values, edit the user’s profile directly in the Okta admin console under the “Profile” tab. Changes are reflected in Prowler Cloud the next time the user logs in via SAML.
   User Type and Role AssignmentThe userType attribute controls which Prowler role is assigned to the user:

   • If a role with the specified name already exists in Prowler Cloud, the user automatically receives that role.
   • If the role does not exist, Prowler Cloud creates a new role with that exact name with read-only access: the user can see all providers and their findings but cannot manage anything. A Prowler administrator (a user whose role includes the “Manage Account” permission) can adjust its permissions afterward through the RBAC Management tab.
   • userType must contain a single value. If the IdP sends multiple values, Prowler Cloud uses only the first value and does not assign multiple roles.

   Fallback Role Without userTypeIf userType is not defined in the user’s Okta profile, the user’s existing roles in Prowler Cloud are left unchanged. Users without an existing role in that tenant receive a least-privilege read_only fallback role until a Prowler administrator assigns another role. If read_only already belongs to a role with different permissions, Prowler Cloud checks suffixed names in order, starting with read_only_0. It reuses the first role with the fallback permissions or creates the first available name.Example: To assign the IT role to a user, set the userType value to IT in Okta. If a role named IT already exists in Prowler Cloud, the user receives it automatically upon login. If it does not exist, Prowler Cloud creates a new role called IT with read-only access, and a Prowler administrator can adjust its permissions as needed.
   With this step, the Okta app catalog configuration is complete. Users can now access Prowler Cloud using either IdP-initiated or SP-initiated SSO flows.
8. Download Metadata XML: Inside the “Sign On” section, go to the “Metadata URL” and download the metadata XML file. Jump to Step 4: Upload IdP Metadata to Prowler.

​

Step 4: Upload IdP Metadata to Prowler

1. Return to the Prowler SAML configuration page.
2. Enter the primary email domain for the organization (e.g., mycompany.com). Prowler Cloud uses this domain to generate the Assertion Consumer Service (ACS) URL. Every configured domain can identify users who authenticate through this SAML configuration.
3. Upload the metadata XML file downloaded from the IdP.

​

Step 5: Save and Verify Configuration

​

Add Multiple SAML Domains

1. Enter the domain in Additional Email Domains.
2. Click Add. Each additional domain must be unique and must differ from the primary domain.
3. Repeat these steps for every domain that must share the configuration.
4. Click Save for a new configuration or Update for an existing configuration.

​

Remove SAML Configuration

​

IdP-Initiated SSO

1. Navigate to the IdP dashboard or portal
2. Click the Prowler Cloud application tile
3. The system automatically authenticates users and redirects them to Prowler Cloud

​

SP-Initiated SSO

1. Navigate to the Prowler login page
2. Click “Continue with SAML SSO”
3. Enter their email address from the configured domain
4. The system redirects users to the IdP for authentication
5. After successful authentication, users are returned to Prowler Cloud

​

Developer and Administrator Guide

​

Environment Configuration

​

SAML API Reference

• Endpoint: /api/v1/saml-config
• Methods:
  • GET: Retrieve the current SAML configuration for the tenant.
  • POST: Create a new SAML configuration.
  • PATCH: Update an existing SAML configuration.
  • DELETE: Remove the SAML configuration.

​

SAML Initiate Endpoint

• Endpoint: POST /api/v1/accounts/saml/initiate/
• Description: This endpoint initiates the SAML login flow. It takes an email address, determines if the domain has a SAML configuration, and redirects the user to the appropriate IdP login page. It is primarily designed for browser-based flows.

​

Testing SAML Integration

​

1. Expose the Local Environment

ngrok http 8080

​

2. Update DJANGO_ALLOWED_HOSTS

DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,prowler-api,*.ngrok.io

​

3. Configure the IdP

​

4. Configure Prowler via API

curl --location 'http://localhost:8080/api/v1/saml-config' \
--header 'Content-Type: application/vnd.api+json' \
--header 'Accept: application/vnd.api+json' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>' \
--data '{
  "data": {
    "type": "saml-configurations",
    "attributes": {
      "email_domain": "yourdomain.com",
      "metadata_xml": "<PASTE_YOUR_IDP_METADATA_XML_HERE>"
    }
  }
}'

​

5. Initiate Login Flow