How to Configure SAML 2.0 SSO

Advanced 30 minutes Org Admins Team & Access Management

Set up SAML-based single sign-on with enterprise identity providers like ADFS, CyberArk Identity, BeyondTrust, or Okta.

Overview

Chainsaw supports SAML 2.0 alongside OIDC for organizations whose identity providers or PAM platforms primarily use SAML. This is common in environments running CyberArk PVWA, BeyondTrust Password Safe, ADFS, or Shibboleth.

Chainsaw acts as a SAML Service Provider (SP). Your identity provider (IdP) authenticates users and sends a SAML assertion back to Chainsaw, which maps the user to a local account.

Prerequisites

  • Owner or Admin role in Chainsaw
  • Access to your SAML IdP admin console
  • The IdP must support SAML 2.0 (ADFS, Okta, Azure AD, Ping Identity, CyberArk Identity, etc.)

Step 1: Collect Chainsaw SP Information

Navigate to Settings > SSO and select SAML 2.0 as the protocol. Chainsaw displays two values you need to register in your IdP:

ValueDescription
SP Metadata URLYour IdP can fetch this to auto-configure the trust relationship
ACS URLThe Assertion Consumer Service endpoint where SAML responses are posted

Copy both values.

Most IdPs can import the SP Metadata URL directly, which auto-fills the ACS URL, Entity ID, and certificate. Try this first before manual configuration.

Step 2: Register Chainsaw in Your IdP

Create a new SAML application in your identity provider.

Common Settings

SettingValue
Entity ID / AudienceThe SP Metadata URL shown by Chainsaw
ACS URL (Reply URL)https://your-domain/chainsaw/api/auth/saml/acs
Name ID FormatemailAddress (recommended)
Name ID ValueUser’s email address

Attribute Statements (Claims)

Configure your IdP to send these attributes in the SAML assertion:

Attribute NameValueRequired
emailUser’s email addressYes
displayNameUser’s full nameRecommended
groupsUser’s group membershipsFor group-to-role mapping
The attribute names must match what you configure in Chainsaw (Step 3). If your IdP uses different names (e.g. Microsoft uses URN-style claim URIs), Chainsaw recognizes common variants automatically, but you can also set custom attribute names.

Provider-Specific Notes

ADFS

  • Add a Relying Party Trust using the SP Metadata URL
  • Configure claim rules to send email, name, and group attributes

Okta

  • Create a new SAML 2.0 application
  • Set Single Sign-On URL to the ACS URL
  • Set Audience URI to the SP Metadata URL entity ID

Azure AD (Entra ID)

  • Create an Enterprise Application > Non-gallery application
  • Configure SAML SSO and set the Reply URL and Identifier
  • Map user attributes under Attributes & Claims

CyberArk Identity

  • Add Chainsaw as a SAML Application
  • Upload the SP metadata or manually configure the ACS URL
  • Map CyberArk roles to SAML group claims

Step 3: Configure SAML in Chainsaw

Navigate to Settings > SSO and select SAML 2.0:

  1. Enter the IdP Metadata URL (your IdP’s SAML metadata endpoint)
  2. Verify or customize the attribute mapping:
    • Email Attribute (default: email)
    • Name Attribute (default: displayName)
    • Groups Attribute (default: groups)
  3. Set the Name ID Format if your IdP uses something other than email
  4. Configure allowed email domains, JIT provisioning, and default role
  5. Toggle Enabled to on
  6. Click Save Configuration

Chainsaw auto-generates an SP signing certificate on first save. The certificate is included in the SP metadata.

Step 4: Test the SAML Flow

  1. Open a new browser or incognito window
  2. Navigate to your Chainsaw login page
  3. Click Sign in with SSO
  4. You should be redirected to your identity provider
  5. Authenticate with your corporate credentials
  6. You should be redirected back to Chainsaw and logged in

Step 5: Troubleshooting

Common Issues

IssueCauseFix
ACS URL mismatchChainsaw URL doesn’t match IdP configVerify exact URL in IdP matches the ACS URL shown by Chainsaw
Invalid assertion signatureIdP cert rotationRe-import IdP metadata in Chainsaw
Attribute not foundClaim name mismatchCheck attribute mapping in Chainsaw matches your IdP’s claim names
Clock skew errorTime difference between serversSync both servers with NTP (SAML allows 5-minute skew)
User not provisionedJIT disabled and no existing accountEnable JIT provisioning or pre-invite the user

Checking Logs

# Docker
docker logs chainsaw | grep -i "saml\|sso\|auth"

# Binary
journalctl -u chainsaw | grep -i "saml\|sso\|auth"

Best Practices

  • Use IdP Metadata URL over XML paste – metadata URLs auto-update when certificates rotate
  • Enable JIT provisioning for frictionless onboarding
  • Configure group-to-role mappings to automate role assignment from IdP groups
  • Test with a single user first before enabling for the entire organization
  • Keep password login as a fallback until SAML is proven stable
  • Skip local 2FA when your IdP already enforces MFA

Next Steps