SAML Authentication

Ascender Ledger Pro can delegate sign-in to your organization's identity provider (IdP) using SAML 2.0. Ledger Pro acts as the Service Provider (SP): it never stores SSO passwords, and it provisions accounts automatically the first time a user signs in.

Before you begin

You need all of the following:

• An application registered for Ledger Pro in your identity provider. Most providers call this an application, a client, or a relying party.
• The IdP metadata for that application: its issuer (entity ID), single sign-on URL, and signing certificate.
• Administrator access to Ledger Pro, so you can reach Settings then Authentication.
• Ledger Pro served over HTTPS. Sign-in works without TLS, but one validation step is skipped. See Serve Ledger Pro over HTTPS.

How SAML sign-in works

1. The user selects Log in to your Company on the Ledger Pro login page.
2. Ledger Pro builds an authentication request and sends it to your IdP's single sign-on URL using the configured binding method.
3. The user authenticates at the IdP.
4. The IdP posts a signed SAML response back to Ledger Pro's assertion consumer service (ACS) endpoint.
5. Ledger Pro validates the response, maps the returned attributes to account fields, creates or updates the local account, reconciles team membership, and starts the session.

Sign-in started from the IdP's own dashboard (IdP-initiated sign-in) is also supported. Every validation still applies, except the correlation between the response and a request Ledger Pro sent.

SAML endpoints

These endpoints are public and do not require an existing session, because your IdP posts to them across sites.

Configure SAML in Ledger Pro

Open Settings, select Authentication, then select the SAML tab. Turn on Enable SAML and complete both columns, then select Save.

Enabling SAML adds a Log in to your Company button to the login page. Local and LDAP sign-in continue to work, so you do not lose access to the local admin account while you are setting SAML up.

Service Provider information

This column describes Ledger Pro itself. You register these values with your identity provider.

The ACS URL is also the value Ledger Pro sends as the AssertionConsumerServiceURL in its authentication request, so your identity provider must accept it as a valid reply URL for the application.

Identity Provider information

This column describes your IdP. Every value comes from the IdP metadata for the application you registered.

Binding method

Binding Method controls how Ledger Pro sends its authentication and logout requests to the IdP:

Both are supported, and most identity providers accept either. Your IdP always returns its response to the ACS endpoint by HTTP POST, whichever binding you choose for the outgoing request.

Sign requests

Signing outgoing requests is optional. It lets the IdP verify that a request genuinely came from your Ledger Pro instance. If your IdP requires signed requests, turn on Sign Requests and upload an X.509 certificate and private key.

A self-signed pair is acceptable for most providers. To generate one:

openssl req -newkey rsa:2048 -nodes -keyout private.pem -x509 -days 365 -out certificate.pem

If your identity provider requires a certificate signed by a known certificate authority, have the certificate signed before uploading it.

Serve Ledger Pro over HTTPS

When Ledger Pro starts a sign-in, it stores the request ID in a short-lived cookie marked Secure, then checks that the IdP's response corresponds to that request. On a deployment that browsers reach over plain HTTP, the cookie is dropped and Ledger Pro treats the response as IdP-initiated, skipping only that correlation check. All signature, issuer, audience, destination, and timestamp validation still applies.

Serve Ledger Pro over HTTPS in production so this check is active. A TLS-terminating proxy satisfies this as long as the browser reaches Ledger Pro over https://.

How responses are validated

Ledger Pro rejects any SAML response that fails any of these checks:

Attribute mapping

Your IdP decides which attributes it sends in the assertion. Configuring that mapping in the IdP is the step most often missed, because Ledger Pro can only populate the fields your IdP actually sends.

Ledger Pro normalizes each incoming attribute name by taking the last path segment of the attribute Name, falling back to its FriendlyName, and lower-casing it. A claim sent as http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress therefore arrives as emailaddress and maps to the email field. You do not need to strip the schema prefix yourself.

Ledger Pro recognizes these attribute names:

Notes on this table:

• Any one of the listed aliases works. Send mail or email or emailaddress, whichever your IdP produces natively.
• Both group and groups are accepted. The SAML 2.0 specification uses the singular form, but many identity providers send the plural, so Ledger Pro handles either.
• Ledger Pro resolves the account by username first, or by name ID when no username attribute is present, then by email. When no account matches, it creates one with the type saml.
• role populates a profile field that Ledger Pro stores on the account but does not currently act on. Identity providers that send a role or group list by default, Keycloak among them, will populate it. There is no need to suppress the attribute at the identity provider.
• Display name and email are refreshed from the IdP on every sign-in. The display name is derived from given name plus surname, then a full-name attribute, then username, then email.

Mapping groups to teams

Team membership is driven entirely by the group or groups attribute.

1. Configure your IdP to send group or role membership in a group or groups attribute.
2. In Ledger Pro, open Admin then Teams, and set the SAML Group Name field on each team to the matching group name from your IdP.

On every SAML sign-in, for each team that has a SAML Group Name configured, Ledger Pro adds the user when the assertion's group values contain that name and removes the user when they do not. Teams with no SAML Group Name are left untouched, so locally managed teams are unaffected.

Because your IdP is authoritative for group membership, removing a user from a group in the IdP removes them from the corresponding Ledger Pro team on their next sign-in.

Logging out

When a SAML user logs out of Ledger Pro, the local Ledger Pro session is cleared and the user is returned to the login page.

This is normal for many single sign-on deployments: identity providers commonly end sessions on their own schedule or after a period of inactivity rather than on demand.

Testing your configuration

Save the SAML settings first, then use the Test button on the SAML settings page. It validates the saved configuration: required fields are present, the certificates and key parse correctly, and the service provider can be assembled.

The test does not perform a browser round trip to your IdP. Confirm end-to-end sign-on by signing out and selecting Log in to your Company on the login page, using an account that is a member of at least one mapped group.

Troubleshooting

Set DEBUG=true to log the full assertion and each validation step. See Configuration for logging options.

If sign-in still fails after working through this table, contact CIQ Support with the debug log for a failed attempt.

Finding the exact values Ledger Pro sends

Mismatches between Ledger Pro and your identity provider are usually a character-level difference in the SP Entity ID, and the fastest way to settle one is to read the authentication request Ledger Pro actually builds.

Request the SAML sign-in endpoint and decode the SAMLRequest value out of the form it returns:

curl -s https://ledger.example.com/login_saml/ \
  | grep -o 'name="SAMLRequest" value="[^"]*"' \
  | sed 's/.*value="//; s/"$//' \
  | base64 -d

The decoded XML shows the exact Issuer (your SP Entity ID), AssertionConsumerServiceURL, Destination, and ProtocolBinding that Ledger Pro is sending. Register those values at your identity provider verbatim.

Identity provider example: Auth0

Auth0 is a convenient provider to validate a configuration against, and a developer account is free. The same values exist in every SAML 2.0 provider under different names.

In Auth0, create an application, then open its Addons tab and enable SAML2 Web App. The Usage tab of that addon exposes the IdP metadata, the identity provider login URL, and the signing certificate.

Map the values as follows:

Two Auth0 specifics are worth calling out:

• Auth0 does not send a full name attribute by default, and it identifies users by nickname rather than username. Both map correctly in Ledger Pro, but declare the attributes you want in the Settings tab of the SAML2 addon.
• Groups are not available in a base Auth0 tenant. Add the Auth0 authorization extension, create roles or groups there, and have the addon send them as a groups attribute.

Related

• Admin Section: users, teams, servers, and settings.
• LDAP Authentication: directory sign-in as an alternative or a complement to SAML.
• Configuration: logging and system configuration options.