Configure SSO / SAML

AttackLens supports Single Sign-On (SSO) using the SAML 2.0 protocol. When configured, your team members authenticate through your organization's identity provider (IdP) -- such as Okta, Azure AD (Entra ID), OneLogin, or any SAML 2.0 compliant provider -- instead of managing separate passwords in AttackLens.

INFO

Requires Super Admin role.

Prerequisites

Before configuring SSO, ensure you have:

• Identity provider access: Administrative access to your organization's IdP to create a new SAML application.
• IdP metadata: You will need the IdP's Entity ID, SSO URL, and X.509 certificate. These are typically available in the IdP's SAML application configuration.
• Super Admin account: At least one Super Admin account with local (non-SSO) credentials. This ensures you can still access AttackLens if the SSO configuration has issues.

WARNING

Always keep at least one local Super Admin account as a break-glass mechanism. If your identity provider goes down or the SAML configuration is misconfigured, you need a way to sign in and fix the settings.

Step 1: Get Service Provider Details

Before configuring your IdP, you need the AttackLens Service Provider (SP) details. Navigate to Settings > SSO / SAML.

The Service Provider section displays the values you will enter in your IdP:

Field	Description	Example
Entity ID	The unique identifier for AttackLens as a Service Provider.	https://your-attacklens-instance:8080/saml/metadata
ACS URL	The Assertion Consumer Service URL where the IdP sends SAML responses after authentication.	https://your-attacklens-instance:8080/saml/acs
Metadata URL	The SAML metadata endpoint. Some IdPs can import configuration automatically from this URL.	https://your-attacklens-instance:8080/saml/metadata

Copy these values -- you will need them when creating the SAML application in your IdP.

Step 2: Create a SAML Application in Your IdP

The exact steps vary by identity provider. Below are guides for common IdPs.

Okta

1. In the Okta Admin Console, go to Applications > Create App Integration.
2. Select SAML 2.0 and click Next.
3. Set the App name to "AttackLens".
4. In Single sign-on URL, paste the ACS URL from AttackLens.
5. In Audience URI (SP Entity ID), paste the Entity ID from AttackLens.
6. Configure attribute statements (see Attribute Mapping below).
7. Click Next, then Finish.
8. From the Sign On tab, copy the Identity Provider metadata URL or download the IdP certificate.

Azure AD (Entra ID)

1. In the Azure portal, go to Enterprise Applications > New application > Create your own application.
2. Name it "AttackLens" and select Integrate any other application you don't find in the gallery (Non-gallery).
3. Go to Single sign-on > SAML.
4. In Basic SAML Configuration:
   • Identifier (Entity ID): Paste the Entity ID from AttackLens.
   • Reply URL (ACS URL): Paste the ACS URL from AttackLens.
5. In Attributes & Claims, configure the attribute mapping (see below).
6. Download the Certificate (Base64) from the SAML Signing Certificate section.
7. Copy the Login URL and Azure AD Identifier from the Set up section.

OneLogin

1. In OneLogin, go to Applications > Add App.
2. Search for "SAML Custom Connector (Advanced)" and select it.
3. Set the Display Name to "AttackLens".
4. In Configuration:
   • ACS (Consumer) URL: Paste the ACS URL.
   • Audience: Paste the Entity ID.
5. In Parameters, configure the attribute mapping.
6. From SSO, copy the Issuer URL and SAML 2.0 Endpoint (HTTP), and download the certificate.

Step 3: Configure Identity Provider Settings in AttackLens

Back in AttackLens, on the Settings > SSO / SAML page, fill in the Identity Provider section:

Entity ID (Required)

The identity provider's Entity ID (also called Issuer). This is a unique identifier for your IdP.

Examples:

• Okta: http://www.okta.com/exk1234567890
• Azure AD: https://sts.windows.net/your-tenant-id/
• OneLogin: https://app.onelogin.com/saml/metadata/123456

SSO URL (Required)

The identity provider's Single Sign-On URL. This is where AttackLens redirects users to authenticate.

Examples:

• Okta: https://yourcompany.okta.com/app/attacklens/exk123/sso/saml
• Azure AD: https://login.microsoftonline.com/your-tenant-id/saml2
• OneLogin: https://yourcompany.onelogin.com/trust/saml2/http-post/sso/123456

X.509 Certificate (Required)

The identity provider's signing certificate in PEM format. This is used to verify that SAML responses actually came from your IdP and were not tampered with.

Paste the full certificate including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

WARNING

The certificate has an expiration date. Set a reminder to update the certificate in AttackLens before it expires. When the certificate expires, SSO authentication will fail.

Step 4: Configure Attribute Mapping

SAML attribute mapping defines how user attributes from your IdP are mapped to AttackLens user fields. Configure the following mappings in both your IdP and AttackLens:

AttackLens Field	SAML Attribute	Required	Description
Email	email or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	Yes	The user's email address. Used as the unique identifier in AttackLens.
First Name	firstName or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	Yes	The user's first name.
Last Name	lastName or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	Yes	The user's last name.
Role	role or http://schemas.microsoft.com/ws/2008/06/identity/claims/role	No	The user's AttackLens role (Viewer, Posture Manager, Admin, Super Admin). If not mapped, new users default to Viewer.

TIP

If your IdP supports group-to-role mapping, configure it in the Role attribute. For example, map an IdP group called "Security Admins" to the AttackLens role "Admin". This automates role assignment and keeps it in sync with your IdP groups.

Step 5: Test the Connection

Before enforcing SSO for all users, test the configuration:

1. Click Test Connection on the SSO settings page.
2. A new browser window opens and redirects you to your IdP's login page.
3. Authenticate with a test user account.
4. If successful, you are redirected back to AttackLens with a success message showing the mapped attributes.

Review the test result to confirm:

• The email, first name, and last name are correctly mapped.
• The role is correctly mapped (if configured).
• No attribute mapping errors are shown.

WARNING

If the test fails, do not enable SSO enforcement. Common issues include:

• Certificate mismatch: The certificate in AttackLens does not match the one used by the IdP. Re-download and paste the correct certificate.
• ACS URL mismatch: The ACS URL in the IdP does not exactly match the one shown in AttackLens (check for trailing slashes, http vs https).
• Entity ID mismatch: The Entity ID in the IdP does not match the one in AttackLens.
• Missing attributes: The IdP is not sending required attributes (email, first name, last name). Verify the attribute statements in the IdP configuration.

Step 6: Save and Enable

After a successful test:

1. Click Save to store the SSO configuration.
2. Toggle Enable SAML SSO to activate SSO.

Once enabled, the AttackLens login page will show a Sign in with SSO button in addition to the standard email/password form.

How SSO Login Works

When a user clicks Sign in with SSO:

1. AttackLens redirects the user to the IdP's SSO URL.
2. The user authenticates with the IdP (username/password, MFA, etc.).
3. The IdP sends a signed SAML response back to AttackLens's ACS URL.
4. AttackLens validates the response signature using the IdP certificate.
5. AttackLens extracts the user attributes (email, name, role).
6. If the user already exists in AttackLens (matched by email), they are signed in.
7. If the user does not exist, a new account is created automatically with the mapped attributes and role (or Viewer if no role is mapped).

User Provisioning

Just-in-Time (JIT) Provisioning

When SSO is enabled, AttackLens supports JIT provisioning. Users do not need to be created in advance -- when a user authenticates through the IdP for the first time, their account is automatically created in AttackLens with:

• Name from the SAML attributes.
• Email from the SAML attributes.
• Role from the SAML role attribute (or Viewer if not mapped).

Deprovisioning

Removing a user from the IdP application prevents them from signing in via SSO. However, their AttackLens account remains active. To fully remove access:

1. Remove the user from the SAML application in your IdP.
2. Disable or delete the user account in AttackLens.

Disabling SSO

To disable SSO:

1. Navigate to Settings > SSO / SAML.
2. Toggle Enable SAML SSO off.
3. Click Save.

The Sign in with SSO button is removed from the login page. Users must sign in with their email and password. SSO-provisioned users who do not have a password set will need a password reset from a Super Admin.