Single Sign-On (SSO)

Overview

AppSec Reporter supports enterprise Single Sign-On so users can authenticate with your existing identity provider (IdP) instead of managing a separate password. The SSO configuration page is available at /sso and is restricted to administrators.

Local username and password authentication remains available as a fallback and can be disabled per-configuration once SSO is working reliably.

Supported Protocols

Only one SSO provider can be enabled at a time. Choose the protocol that matches your identity provider:

  • OIDC / OAuth 2.0 — OpenID Connect with Authorization Code Flow and PKCE. Works with Google Workspace, Microsoft Entra ID (Azure AD), Okta, Auth0, Keycloak, and most modern IdPs.
  • SAML 2.0 — SP-initiated login via HTTP-Redirect binding. Common in enterprise deployments using Okta, OneLogin, PingIdentity, or ADFS.
  • WS-Federation — Passive Requestor Profile, typically used with Microsoft Entra ID or Okta via ADFS.

Creating an SSO Configuration

From the SSO page, click Create Configuration and fill in the shared fields below, then the protocol-specific fields in the next section.

  • Display Name — label shown on the login page button (e.g. "Sign in with Okta").
  • Protocol — OIDC, SAML, or WS-Federation.
  • IdP Entity ID — issuer or realm identifier provided by your IdP.
  • Domain Restriction — optional comma-separated list of email domains allowed to sign in (e.g. example.com,partner.com). Leave empty to allow any domain.
  • Auto-provision Users — if enabled, users who sign in via SSO for the first time are created automatically. If disabled, an admin must pre-create the account.
  • Default Role — role assigned to auto-provisioned users when no role mapping matches: viewer, analyst, or admin.
  • Allow Local Auth Fallback — keep local username/password login available alongside SSO. Recommended during initial rollout.
  • Role Mapping — map IdP claims (groups, roles) to local roles. See Role Mapping below.

Protocol-Specific Configuration

OIDC / OAuth 2.0

  • Client ID — application client ID from your IdP.
  • Client Secret — client secret from your IdP. Stored encrypted at rest.
  • Issuer URL — the iss value expected in issued tokens.
  • Authorization Endpoint — IdP URL where users are redirected to log in.
  • Token Endpoint — IdP URL used to exchange the authorization code.
  • UserInfo Endpoint — optional; used to fetch claims not in the ID token.
  • JWKS URI — endpoint used to verify the ID token signature.
  • Scopes — OAuth scopes requested. Defaults to openid profile email.
  • PKCE Enabled — recommended; enabled by default.

SAML 2.0

  • SP Entity ID — this application's identifier, registered with the IdP.
  • IdP SSO URL — where SAML AuthnRequests are sent.
  • IdP SLO URL — optional Single Logout endpoint.
  • NameID Format — format used in the Subject element, e.g. emailAddress or persistent.
  • Want Assertions Signed — reject assertions without a valid signature. Recommended.
  • Attribute Mappings — map SAML attributes to local fields (e.g. email, name, groups).
  • IdP Signing Certificate — required when signature validation is enforced. See Certificates.

WS-Federation

  • Realm — the wtrealm identifier registered with the IdP.
  • Metadata Endpoint — IdP federation metadata URL.
  • Login URL — IdP sign-in endpoint.
  • Logout URL — optional sign-out endpoint.
  • Signing Certificate — used to verify the SAML token inside the WS-Federation response.

Metadata Discovery

Instead of entering every endpoint by hand, you can paste an IdP metadata URL and click Discover. The system fetches and parses the metadata to auto-populate:

  • OIDC: authorization, token, userinfo, and JWKS endpoints.
  • SAML: SSO URL, SLO URL, and the IdP signing certificate.
  • WS-Federation: login URL and signing certificate.

You can refresh the configuration from the metadata URL at any time to pick up endpoint or certificate changes.

Certificates

Certificates can be uploaded in PEM, DER (.cer), or PKCS#7 (.p7b) format.

  • Certificates are encrypted at rest.
  • SHA256 fingerprint and expiration date are stored for audit.
  • The SSO page shows a warning when a certificate is approaching expiry.
  • To rotate, upload the new certificate and save — no downtime required as long as the new certificate is trusted by the IdP.

Role Mapping

Role mapping lets you assign local roles based on group or role claims from your IdP. Configure:

  • Claim Name — the IdP claim that contains groups or roles (e.g. groups, roles).
  • Mapping — a dictionary mapping IdP values to local roles, for example:
{
  "AppSec-Admins": "admin",
  "AppSec-Analysts": "analyst",
  "AppSec-Viewers": "viewer"
}

On login, the first matching claim value wins. If no value matches, the Default Role is used.

Testing a Configuration

Before enabling a configuration for all users, use the Test action on the SSO page. This exercises the end-to-end flow against the IdP and reports any issues with endpoints, certificates, or claim extraction.

End-User Login Flow

  1. On the login page, click Sign in with [Display Name].
  2. Your browser is redirected to the IdP login page.
  3. Authenticate at the IdP (password, MFA, etc.).
  4. The IdP redirects back to AppSec Reporter. The system verifies the response, resolves or creates the user, and issues a session token.
  5. You are redirected to the dashboard.

If domain restriction or role mapping rejects the login, the user sees an error on the login page and the event is written to the audit log.

Environment Variables

The following environment variables control SSO behavior at the deployment level:

  • APPSEC_SSO_BASE_URL — public backend URL that IdPs redirect to (e.g. https://appsec.example.com).
  • APPSEC_SSO_CALLBACK_URL — frontend URL that receives the session token after SSO (e.g. https://appsec.example.com/sso-callback).
  • APPSEC_SSO_STATE_COOKIE_MAX_AGE — state/nonce cookie lifetime in seconds. Defaults to 300 (5 minutes).

Security Controls

  • CSRF protection — a state parameter stored in an httpOnly cookie is validated on callback.
  • Token verification — OIDC ID tokens are verified via JWKS; SAML assertions are verified with xmlsec; WS-Federation tokens are verified using the configured signing certificate.
  • Condition checks — SAML NotBefore and NotOnOrAfter are enforced with a 2-minute clock skew; OIDC nonce, issuer, audience, and expiry are validated.
  • Encryption at rest — client secrets and certificates are encrypted with Fernet.
  • Rate limiting — SSO init and callback endpoints are limited to 30 requests per minute.
  • Audit logging — configuration changes and every login success or failure are recorded.

Troubleshooting

  • Login button not visible — the configuration is disabled, or APPSEC_SSO_BASE_URL does not match the URL users are browsing.
  • "Invalid state" error — the state cookie expired before the IdP redirected back. Increase APPSEC_SSO_STATE_COOKIE_MAX_AGE or check for clock skew.
  • Signature validation failure (SAML/WS-Fed) — the IdP signing certificate is missing, expired, or does not match the certificate in use at the IdP. Refresh metadata or re-upload the certificate.
  • "User not found" — auto-provisioning is disabled and the account has not been pre-created, or the email domain is not in the allowed list.
  • Wrong role assigned — review the role mapping and the claim name; inspect the raw IdP response from the audit log.