SAML Single Sign-On (SSO)¶

Edition note: SAML SSO is a commercial feature. The community edition supports only local user authentication.

Overview¶

Faraday supports SAML 2.0 for single sign-on integration with external identity providers (IdPs). This enables centralized authentication through your organization's existing identity infrastructure.

Key Characteristics¶

Supported Identity Providers¶

Any SAML 2.0-compliant IdP can be configured using the generic settings below.

SAML Endpoints¶

Faraday exposes four SAML endpoints. All IdP configurations reference these URLs using your Faraday server's domain.

Replace <domain> with your Faraday server's fully qualified domain name (e.g., faraday.example.com).

Configuration¶

Via Command Line¶

faraday-manage settings -a update saml

Interactive prompts:

$ faraday-manage settings -a update saml
Update settings for: saml
enabled [False]:
display_name [Identity Provider]:
user_role [admin]:
admin_group []:
attribute_identifier []:
sso_url [http://localhost/saml/login]:
sp_certificate []:
sp_private_key []:
idp_certificate []:
Do you confirm your changes on saml?
[Y/n]:

Via Web UI¶

Navigate to User menu (top-right) → Preferences → Authentication → SAML and configure the settings through the graphical interface.

Restart Required¶

After any SAML configuration change, restart the server:

systemctl restart faraday-server

Settings Reference¶

General Settings¶

Identity Provider Settings¶

User & Role Settings¶

Service Provider Certificate Settings¶

Generating SP Certificates¶

Each Faraday instance requires its own Service Provider certificate/key pair for signing SAML requests. Generate a self-signed certificate:

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 1825 -out certificate.pem

This produces:

• certificate.pem → paste contents into SP Certificate setting
• key.pem → paste contents into SP Private Key setting

Tip: The -days 1825 flag creates a 5-year certificate. Adjust as needed by your organization's security policy.

When pasting certificate contents into the CLI or UI, include the full PEM block including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- delimiters.

Authentication Flow¶

    ┌───────────┐     ┌──────────────┐     ┌───────────────┐
    │  Browser  │     │   Faraday    │     │  Identity     │
    │  (User)   │     │   Server     │     │  Provider     │
    └─────┬─────┘     └──────┬───────┘     └───────┬───────┘
          │                  │                     │
          │  1. Click SSO    │                     │
          │  login button    │                     │
          ├─────────────────►│                     │
          │                  │                     │
          │  2. SAML AuthnRequest                  │
          │◄─────────────────┤  (redirect to IdP)  │
          │─────────────────────────────────────────►
          │                  │                     │
          │  3. User authenticates at IdP          │
          │◄────────────────────────────────────────
          │                  │                     │
          │  4. SAML Assertion (POST to ACS)       │
          ├─────────────────►│                     │
          │                  │                     │
          │  5. Validate     │                     │
          │  assertion,      │                     │
          │  create/update   │                     │
          │  user session    │                     │
          │                  │                     │
          │  6. Redirect to  │                     │
          │  Faraday UI      │                     │
          │◄─────────────────┤                     │
          │                  │                     │

1. User clicks the SSO login button (labeled with display_name) on the Faraday login page.
2. Faraday redirects to the IdP's sso_url with a SAML AuthnRequest.
3. User authenticates at the IdP (credentials, MFA, etc.).
4. IdP posts a signed SAML assertion back to Faraday's ACS endpoint.
5. Faraday validates the assertion signature using the idp_certificate, extracts the username from attribute_identifier, and creates or updates the user with user_type = 'saml'.
6. User is redirected to the Faraday web interface with an active session.

Role Assignment¶

Default Role¶

All new SAML users receive the role specified in user_role (default: admin).

Security recommendation: Change the default user_role to pentester or a lower-privilege role and use admin_group for explicit admin assignment.

Admin Group Mapping¶

When admin_group is configured, Faraday checks the SAML assertion for a matching group/role attribute. Users whose assertion includes this group value are assigned the admin role; others receive the user_role default.

Available Roles¶

SAML + API Tokens¶

SAML-authenticated users can obtain API tokens for programmatic access:

1. User completes SAML SSO login flow
2. After successful assertion, Faraday creates a session
3. User calls GET /_api/v3/token to obtain a JWT
4. JWT is used for subsequent API calls via Authorization: Token <jwt>

This enables automated workflows (CI/CD, scripts) even when primary authentication is via SSO.

SAML + Local Users¶

Unlike LDAP, SAML coexists with local user accounts. Both authentication methods work simultaneously:

• Local users log in with username/password
• SAML users click the SSO button and authenticate via the IdP

This is useful for maintaining a local admin account as a fallback.

Troubleshooting¶

Verifying SAML Configuration¶

To check current SAML settings:

faraday-manage settings -a show saml

To reset SAML configuration:

faraday-manage settings -a update saml
# Set enabled to False, confirm changes
systemctl restart faraday-server

See Also¶

• auth0 — Auth0 SAML integration guide
• google — Google Workspace SAML integration guide
• okta — Okta SAML integration guide
• azure-ad — Microsoft Entra ID (Azure AD) SAML integration guide
• ldap-configuration — LDAP authentication configuration
• server-configuration — Server settings reference