---
title: 'SAML Single Sign-On (SSO)'
sidebarTitle: 'SAML SSO'
---

import { VersionBadge } from "/snippets/version-badge.mdx"
import { AppliesTo } from "/snippets/applies-to.mdx"

<VersionBadge version="5.9.0" />

<AppliesTo />

This guide provides comprehensive instructions to configure SAML-based Single Sign-On (SSO) in Prowler Cloud. This configuration allows users to authenticate using the organization's Identity Provider (IdP).

This document is divided into two main sections:

- **[User Guide](#user-guide-configuration)**: For organization administrators to configure SAML SSO through Prowler Cloud.

- **[Developer and Administrator Guide](#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

Follow these steps to enable and configure SAML SSO for an organization.

### Key Features

Prowler can be integrated with SAML SSO identity providers such as Okta to enable single sign-on for the organization's users. The Prowler SAML integration currently supports the following features:

-   [**IdP-Initiated SSO**](#idp-initiated-sso): Users can initiate login from their Identity Provider's dashboard.
-   [**SP-Initiated SSO**](#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.

<Warning>
**Deactivate SAML**

If the SAML configuration is removed, users who previously authenticated via SAML will need to reset their password to regain access using standard login. This occurs because accounts no longer have valid authentication credentials without the SAML integration.

</Warning>
### 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

To access the account settings, click the "Account" button in the top-right corner of Prowler Cloud, or navigate directly to `https://cloud.prowler.com/profile` (or `http://localhost:3000/profile` for local setups).

![Access Profile Settings](/images/prowler-app/saml/saml-step-1.png)

#### Step 2: Enable SAML Integration

On the profile page, find the "SAML SSO Integration" card and click "Enable" to begin the configuration process.

![Enable SAML Integration](/images/prowler-app/saml/saml-step-2.png)

The next section explains how to configure the IdP settings based on the selected Identity Provider.

#### Step 3: Configure the Identity Provider (IdP)
Choose a Method:

- Use [**Generic Method**](#generic-method) for any SAML 2.0 compliant Identity Provider or when you need custom configuration.
- Use [**Okta App Catalog**](#okta-app-catalog) if you're using Okta and want a simplified setup process with pre-configured settings.

<Tabs>
    <Tab title="Generic Method">
        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 configuration](/images/prowler-app/saml/idp_config.png)

        <Info>
        **IdP Configuration**

        The 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](/user-guide/tutorials/prowler-app-sso-entra). For Google Workspace, see our [Google Workspace configuration instructions](/user-guide/tutorials/prowler-app-sso-google-workspace).

        </Info>

        **Configure Attribute Mapping in the IdP**

        For 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). If `userType` is not defined, the user's existing roles are left unchanged. Role permissions can be edited in the [RBAC Management tab](/user-guide/tutorials/prowler-app-rbac). | No       |
        | `organization` | The user's company name.                                                                                | No       |

        <Info>
        **IdP Attribute Mapping**

        Note 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`.
        ![IdP configuration](/images/prowler-app/saml/saml_attribute_statements.png)

        </Info>
        <Warning>
        **Single-Value `userType` Required**

        Map `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.

        </Warning>
        <Warning>
        **Dynamic Updates**

        Prowler 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.

        </Warning>

    </Tab>
    <Tab title="Okta App Catalog">
        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](https://youtu.be/NjSp5owvCdY).

        1. **Access App Catalog**: Navigate to the IdP's application catalog (e.g., [Browse App Catalog](https://www.okta.com/integrations/) in Okta).

            ![Browse App Catalog](/images/prowler-app/saml/app-catalog-browse.png)

        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.

            ![Search for Prowler](/images/prowler-app/saml/app-catalog-browse-prowler.png)

        3. **Select Prowler Cloud Application**: Click the Prowler Cloud application from the search results to view its details page.

            ![Prowler Application Details](/images/prowler-app/saml/app-catalog-browse-prowler-add.png)

        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.

            ![Add Prowler Configuration](/images/prowler-app/saml/app-catalog-browse-prowler-configure.png)

        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".

            ![Okta App Assignments](/images/prowler-app/saml/okta-app-assignments.png)

        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.

            ![Okta User Profile — First Name and Last Name](/images/prowler-app/saml/okta-user-profile-name.png)

            * **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.

            ![Okta User Profile — User Type and Organization](/images/prowler-app/saml/okta-user-profile-attributes.png)

            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.

            <Warning>
            **User Type and Role Assignment**

            The `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](/user-guide/tutorials/prowler-app-rbac).
            * If `userType` is not defined in the user's Okta profile, the user's existing roles in Prowler Cloud are left unchanged.
            * `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.

            **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.

            </Warning>

            With this step, the Okta app catalog configuration is complete. Users can now access Prowler Cloud using either [IdP-initiated](#idp-initiated-sso) or [SP-initiated SSO](#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).
    </Tab>
</Tabs>

#### Step 4: Upload IdP Metadata to Prowler

Once the IdP is configured, it provides a **metadata XML file**. This file contains the IdP's configuration information, such as its public key and login URL.

To complete the Prowler Cloud configuration:

1.  Return to the Prowler SAML configuration page.

2.  Enter the **email domain** for the organization (e.g., `mycompany.com`). Prowler Cloud uses this to identify users who should authenticate via SAML.

3.  Upload the **metadata XML file** downloaded from the IdP.

![Configure Prowler with IdP Metadata](/images/prowler-app/saml/saml-step-3.png)

#### Step 5: Save and Verify Configuration

Click the "Save" button to complete the setup. The "SAML Integration" card will now display an "Active" status, indicating the configuration is complete and enabled.

![Verify Integration Status](/images/prowler-app/saml/saml-step-4.png)

<Info>
**IdP Configuration**

The exact steps for configuring an IdP vary depending on the provider (Okta, Azure AD, etc.). Please refer to the IdP's documentation for instructions on creating a SAML application.

</Info>

### Remove SAML Configuration
SAML SSO can be disabled by removing the existing configuration from the integration panel.
![Remove SAML configuration](/images/prowler-app/saml/saml-step-remove.png)

### IdP-Initiated SSO

Once SAML SSO is configured, users can access Prowler Cloud directly from their Identity Provider's dashboard:

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

This method is convenient for users who primarily work from the IdP portal and prefer a seamless single-click access.

### SP-Initiated SSO

Users can also initiate the login process directly from Prowler's login page:

1. Navigate to the Prowler login page
2. Click "Continue with SAML SSO"
    ![](/images/prowler-app/saml/saml-signin-1.png)
3. Enter their email address from the configured domain
    ![](/images/prowler-app/saml/saml-signin-2.png)
4. The system redirects users to the IdP for authentication
5. After successful authentication, users are returned to Prowler Cloud

This method is useful when users bookmark Prowler or navigate directly to the application.

---

## Developer and Administrator Guide

This section provides technical details for developers and administrators of Prowler Local Server instances.

### Environment Configuration

For Prowler Local Server deployments, several environment variables must be configured to ensure SAML SSO functions correctly. These variables are typically set in an `.env` file.

| Variable                  | Description                                                                                                                                                             | Example                                                   |
|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| `API_BASE_URL`            | The base URL of the Prowler API instance.                                                                                                                              | `http://mycompany.prowler/api/v1`                         |
| `DJANGO_ALLOWED_HOSTS`    | A comma-separated list of hostnames that the Django backend will accept requests from. Include any domains used to access the Prowler API.                               | `localhost,127.0.0.1,prowler-api,mycompany.prowler`       |
| `AUTH_URL`                | The base URL of the Prowler web UI. This is used to construct the callback URL after authentication.                                                                     | `http://mycompany.prowler`                                |
| `SAML_SSO_CALLBACK_URL`   | The full callback URL where users are redirected after authenticating with the IdP. It is typically constructed using the `AUTH_URL`.                                       | `${AUTH_URL}/api/auth/callback/saml`                      |

After modifying these variables, the Prowler API must be restarted for the changes to take effect.

### SAML API Reference

Prowler provides a REST API to manage SAML configurations programmatically.

-   **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.

<Note>
**API Documentation**

For detailed information on using the API, refer to the [Prowler API Reference](https://api.prowler.com/api/v1/docs#tag/SAML/operation/saml_config_create).

</Note>
#### 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

Follow these steps to test a SAML integration in a development environment.

#### 1. Expose the Local Environment

Since the IdP needs to send requests to the local Prowler instance, it must be exposed to the internet. A tool like `ngrok` can be used for this purpose.

To start ngrok, run the following command:
```bash
ngrok http 8080
```
This command provides a public URL (e.g., `https://<random-string>.ngrok.io`) that forwards to the local server on port 8080.

#### 2. Update `DJANGO_ALLOWED_HOSTS`

To allow requests from ngrok, add its URL to the `DJANGO_ALLOWED_HOSTS` environment variable.

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

#### 3. Configure the IdP

When configuring the IdP for testing, use the ngrok URL for the ACS URL:
`https://<your-ngrok-url>/api/v1/accounts/saml/<YOUR_DOMAIN>/acs/`

#### 4. Configure Prowler via API

To create a SAML configuration for testing, use `curl`. Replace placeholders with actual data.

```bash
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

To test the end-to-end flow, construct the login URL and open it in a browser. This starts the IdP-initiated login flow.

`https://<your-ngrok-url>/api/v1/accounts/saml/<YOUR_DOMAIN>/login/`

If successful, the user will be redirected back to the Prowler application with a valid session.
