Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

04.03 The Authentication Extra Overview

The Authentication Extra adds enterprise SSO to SimpleRisk — SAML 2.0 federation with any compliant IdP (Azure AD, Okta, ADFS, Auth0, etc.) and LDAP/Active Directory authentication. The Extra also handles auto-provisioning of users on first SSO login, attribute mapping for username/email/name, and group-to-team mapping for role assignment.

Requires: Authentication Extra

SAML SSO and LDAP/AD authentication are added by the Authentication Extra at simplerisk/extras/authentication/. Without the Extra activated, SimpleRisk has only Core local authentication (see Local Authentication and Password Policies) — username/password against the local user table.

Why this matters

Most production SimpleRisk deployments end up integrated with enterprise identity. The reasons line up across organizations: SSO removes the per-application credential sprawl (one place to deprovision a departing employee), it enables enterprise-grade MFA and conditional access (Azure Conditional Access, Okta MFA policies, on-prem AD MFA solutions), and it produces auditable centralized authentication logs (the IdP records every authentication event, not just the application).

The Authentication Extra is how SimpleRisk plugs into that identity infrastructure. Once active, users authenticate against the configured IdP rather than against SimpleRisk's local-auth path; SimpleRisk auto-creates user records on first successful SSO login (so the IT team isn't manually pre-provisioning every user); and the IdP's groups can map to SimpleRisk's teams for automatic role assignment.

The honest scope to know up front: the Extra supports SAML 2.0 and LDAP/AD only. There's no native OpenID Connect (OIDC) implementation; for IdPs that offer both SAML and OIDC, configure SAML. There's no Kerberos, no SPNEGO, no client-certificate authentication. The two supported flavors cover the substantial majority of enterprise IdPs (every major SaaS IdP supports SAML 2.0; on-prem AD speaks LDAP), but if your environment is OIDC-only, the path forward is to negotiate SAML support with the IdP.

The other thing worth knowing: only one external auth method is active at a time per install. The configuration is "SAML or LDAP" — pick one. The selection is made in the Extra's settings UI and stored as custom_auth in the settings table. Multi-IdP deployments (Azure for the corporate users and on-prem AD for the legacy users) aren't natively supported; the workaround is to configure one as the SimpleRisk auth method and federate the other through it (e.g., Azure can federate to on-prem AD via Azure AD Connect; Azure becomes the SAML IdP for SimpleRisk).

The third thing: local authentication remains available alongside SSO for users marked type='simplerisk'. The Extra doesn't disable local auth — it adds the SSO option as well. This is by design: the admin account that bootstrapped the install stays a local user, so a misconfigured SSO doesn't lock the operator out. SSO-provisioned users (type='ldap' or type='saml') can only authenticate via their respective external system; local users (type='simplerisk') authenticate against the local-auth path. Both paths produce a session; what differs is the validation step.

How frameworks describe this

Federation, SSO, and centralized identity management are core ground for every major security framework — they're the modern answer to access-management at scale.

  • NIST SP 800-63C (Federation and Assertions) is the federal canon for federated identity; AAL2 and AAL3 assertion levels formalize what "trust this assertion from an IdP" means and what posture the IdP must hold.
  • NIST CSF v2.0 under Protect.AC (Identity Management, Authentication, and Access Control) treats centralized identity as the default expectation; per-application credential stores are the exception that needs justification.
  • ISO/IEC 27001 Annex A A.5.16 (Identity management) and A.5.17 (Authentication information) cover the lifecycle and the operational mechanics; the standard expects identity to be managed through the lifecycle (joiner, mover, leaver) and authentication to be commensurate with the risk of the resource.
  • PCI DSS v4.0 Requirements 7 and 8 — Requirement 8 specifically pushes toward MFA and centralized identity for any access to the cardholder data environment.

The takeaway across all four: federate where possible, deprovision centrally, ensure the IdP's posture matches the application's sensitivity. SimpleRisk's Authentication Extra is the integration surface that lets you participate in that posture.

How SimpleRisk implements this

Activation

Sidebar: Configure → Extras → Authentication Extra → Activate. The activation:

  1. Sets custom_auth = 'true' in the settings table (the master Extra-active flag).
  2. Initializes default settings for SAML and LDAP (most blank or sane defaults; the operator fills in the IdP-specific values).
  3. Generates a self-signed SAML SP certificate (in simplerisk/extras/authentication/cert/) for SAML request signing and assertion encryption. This certificate is the SimpleRisk SP's identity to the IdP; you'll typically upload its public half to the IdP during SAML configuration.
  4. Adds the Authentication settings page to the admin navigation.

The activation doesn't configure SAML or LDAP — it just makes the configuration UI available. You still walk through the IdP-specific configuration (see Configuring SAML SSO, Configuring OIDC, or Active Directory and LDAP) to point SimpleRisk at your IdP.

The auth-method selection model

Once the Extra is active, the configuration UI exposes a dropdown for the active auth method. The options are typically:

  • Local — the default; SSO is configured but not enforced; users authenticate via the Core local-auth path.
  • LDAP — the LDAP/AD path is active; new users coming in via LDAP are auto-provisioned with type='ldap'.
  • SAML — the SAML path is active; new users coming in via SAML are auto-provisioned with type='saml'.

The selection is stored in custom_auth_method (or the equivalent setting; check the active install's settings). Once set, the login page surfaces the SSO option (typically a "Sign in with [your IdP name]" button or auto-redirect, depending on configuration); the local-auth path remains accessible for users with type='simplerisk'.

User provisioning on first SSO login

The auto-provisioning behavior is controlled by AUTHENTICATION_ADD_NEW_USERS (a settings-level toggle). When 1:

  1. A user authenticates against the configured IdP.
  2. SimpleRisk receives the assertion (SAML) or the bind result (LDAP) plus the attributes the IdP sends.
  3. SimpleRisk checks whether a user row exists matching the username from the assertion.
  4. If no row exists, SimpleRisk calls authentication_add_new_user() to create a new user with type='ldap' or type='saml', copying the attributes (email, display name, etc.) from the assertion.
  5. The user gets the default role and team set (as configured in the Authentication Extra's defaults).
  6. The session is established and the user lands in the application.

When AUTHENTICATION_ADD_NEW_USERS = 0, only pre-provisioned users can authenticate; an unknown username from the IdP fails authentication. The 1 posture is operationally simpler (no manual provisioning required); the 0 posture is appropriate when the application's user base is intentionally curated and IdP-known users shouldn't all get SimpleRisk access by default.

Attribute mapping

The Extra reads specific attributes from the IdP assertion to populate the SimpleRisk user record. The configuration:

  • Username attribute (USERNAME_ATTRIBUTE for SAML; AUTHENTICATION_LDAP_USER_ATTRIBUTE for LDAP) — which IdP attribute uniquely identifies the user. Common SAML choices: NameID, email, uid. Common LDAP choices: sAMAccountName, userPrincipalName, mail.
  • Display name attribute (SAML_DISPLAY_NAME_ATTRIBUTE; LDAP equivalent) — the human-readable name to show in the UI.
  • Email attribute (SAML_EMAIL_ATTRIBUTE; LDAP equivalent) — for notifications and audit-trail attribution.
  • Role/group attribute (SAML_ROLE_ATTRIBUTE; LDAP equivalent) — the group(s) the user belongs to in the IdP, used for the group-to-team mapping below.

The IdP-side attribute names are usually configurable on the IdP (the SAML "Attribute Statement" or the LDAP attribute schema). Pick attributes that are stable (don't change when a user moves between teams) and that uniquely identify the user.

Group-to-team mapping

The Extra supports automatic team assignment based on IdP group membership. The data model:

  • remote_team — a table mapping a remote-IdP team identifier (group name from the assertion) to a SimpleRisk team. When a user authenticates and their assertion includes a group name that matches a remote_team entry, the user is assigned to the corresponding SimpleRisk team.
  • ldap_group_and_teams — the LDAP-specific junction table for the same purpose.

This means the team assignment can be driven by the IdP — you manage groups in Azure AD, and SimpleRisk team membership reflects those groups automatically. New group memberships propagate at the user's next login (the assertion arrives with the updated group list and SimpleRisk reconciles the team assignment).

Falling back to local

The Extra never forces all users through SSO. The local-auth path remains active for users with type='simplerisk':

  • The original admin account installed during initial setup keeps type='simplerisk' and authenticates via local credentials.
  • Operators can create additional type='simplerisk' users explicitly (rare; usually the operator account is the only one).
  • A misconfigured SSO doesn't lock the operator out — they can still log in via the local-auth path while debugging the SSO configuration.

This is the right shape. Many other applications make local-auth disable-able; SimpleRisk's posture (always-on local-auth for the admin) is more defensive against IdP outages.

Deactivation

Deactivating the Authentication Extra:

  1. Sets custom_auth = 'false'.
  2. Cleans up the SimpleSAMLphp scratch tables (SimpleSAMLphp_saml_LogoutStore, SimpleSAMLphp_kvstore, SimpleSAMLphp_tableVersion).
  3. Removes the SAML SP certificate (or leaves it on disk for re-activation; check the install).
  4. The auth method reverts to local; SSO-provisioned users (type='ldap', type='saml') can no longer authenticate (their type doesn't match a path that's currently active).

Deactivation is reversible (re-activate, re-configure), but plan for the user-impact: SSO users lose access until either the Extra is re-activated or their type is changed to 'simplerisk' and they're given a local password. Don't deactivate the Extra in production without a plan.

What the Extra doesn't do

A few honest limitations to know up front:

  • No native OIDC. SAML and LDAP are the supported federation surfaces. OIDC-only IdPs need to be reconfigured for SAML or fronted by a SAML-capable broker.
  • No multi-IdP. One method active at a time. Multi-IdP deployments need to consolidate at a single IdP (typically by federating downstream IdPs to a single upstream).
  • No automatic deprovisioning. Removing a user from the IdP doesn't auto-disable them in SimpleRisk; it just prevents their next SSO login. The orphaned local user record persists. Operationally: include "disable in SimpleRisk" in your offboarding workflow.
  • No SCIM. Just-in-time provisioning happens on first login; bulk pre-provisioning via SCIM isn't supported. Programs that want pre-provisioning use the v2 user-management API instead.
  • No Single Logout (SLO) by default. Logging out of SimpleRisk doesn't necessarily log the user out of the IdP (and vice versa). SAML SLO can be configured but is brittle in practice; most deployments don't enable it.

Common pitfalls

A handful of patterns recur with the Authentication Extra.

  • Activating without a configuration plan. The activation makes the configuration available; it doesn't configure anything. An active-but-unconfigured Extra produces no SSO behavior; users keep authenticating locally. Plan the IdP-side and SimpleRisk-side configuration together.

  • Disabling local auth as a "security improvement." Don't. The local-auth path for the operator account is the recovery path when SSO breaks. Programs that want SSO-only for non-operator users can achieve that by ensuring no non-operator users have type='simplerisk' (so the local-auth path only works for operators).

  • Setting AUTHENTICATION_ADD_NEW_USERS = 1 without understanding the posture. Auto-provisioning means anyone with a valid IdP assertion gets a SimpleRisk account on first login. For broad-IdP deployments (every employee in Azure AD), this might be 5,000 unintended user records. Either curate the IdP-side group membership tightly, or set the toggle to 0 and pre-provision explicitly.

  • Forgetting attribute mapping. A SAML configuration that authenticates successfully but maps the username from the wrong attribute can silently produce duplicate user records (the user's display name varies, so SimpleRisk treats each login as a "new" user). Pin the username attribute to a stable, unique value (typically email or userPrincipalName).

  • Ignoring the certificate lifecycle. The SAML SP certificate has an expiration. When it expires, SAML stops working. Track the expiration; rotate before expiry. (See Configuring SAML SSO for the rotation procedure.)

  • Mixing SimpleRisk MFA with IdP MFA expectations. SimpleRisk's MFA only applies to local users. SSO users have their MFA posture determined by the IdP. Don't claim "all users have MFA" because SimpleRisk's MFA toggle is on; verify the IdP-side posture independently.

  • Not testing recovery scenarios. "What happens if SSO is broken?" should have a rehearsed answer. Walk through the local-auth recovery path before you need it.

  • Conflating teams from groups with permissions. Group-to-team mapping affects record visibility (team segregation); it doesn't grant permissions. Permissions still come from the SimpleRisk role assignment. If your IdP groups model both team membership and role, you'll need to map both — teams via remote_team, roles via SimpleRisk role assignment (manually or via additional Extra configuration).

  • Keeping SSO-provisioned users active after they leave the IdP. When a user is offboarded in the IdP, their SimpleRisk record persists. They can't log in (no IdP path), but the audit trail still attributes their historical activity to a "live" account. Include "disable user in SimpleRisk" in the offboarding workflow.

  • Activating the Extra in production without a maintenance window. Activation triggers the SimpleSAMLphp setup, generates certificates, and modifies authentication behavior. Do this during a planned window with operator-account testing on standby.

Related