---
title: 04.04 Configuring SAML SSO
description: Set up SAML 2.0 single sign-on against an external identity provider — configure metadata, attribute mapping, certificate handling, and the…
---
[Skip to content](https://support.simplerisk.com/kb/04-04-configuring-saml-sso#main-content)
English
Show submenu for translations
[Customer portal](https://support.simplerisk.com/tickets?hsLang=en)
[](https://www.simplerisk.com/)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Customer portal](https://support.simplerisk.com/tickets)
- [Contact us](https://www.simplerisk.com/about-us/contact-us)
[Contact us](https://www.simplerisk.com/about-us/contact-us)
How can we help you?
- There are no suggestions because the search field is empty.
1. [SimpleRisk Knowledge Base](https://support.simplerisk.com/kb?hsLang=en)
2. [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en)
3. [04 Authentication](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#04-authentication)
# 04.04 Configuring SAML SSO
## Set up SAML 2.0 single sign-on against an external identity provider — configure metadata, attribute mapping, certificate handling, and the test-before-enforcing workflow for safe rollout.
> **Requires:** *Authentication Extra*
>
> SAML 2.0 single sign-on is provided by the Authentication Extra. Core SimpleRisk supports local username/password and API key authentication only. The Extra appears in the Settings Hub (Settings cog, top-right of any page) → Extras chip as **Custom Authentication** but the management page renders as **Custom Authentication Extra** — same Extra, two names. See [The Authentication Extra Overview](https://support.simplerisk.com/kb/04-03-the-authentication-extra-overview?hsLang=en) for the wider picture.
## Why this matters
Organizations that grow past their first ten SimpleRisk users hit the same pair of pain points: passwords nobody rotates, and accounts nobody disables when the holder leaves. SAML SSO solves both. Authentication moves to the IdP you already run for the rest of the corporate stack (Okta, Microsoft Entra ID, Google Workspace, ADFS, OneLogin), and SimpleRisk inherits its password policy, MFA enforcement, and offboarding behavior. When IT disables a leaver's IdP account on a Friday, that account stops logging into SimpleRisk on Monday. No second list to maintain.
NIST SP 800-63 *Digital Identity Guidelines* and SOC 2's Common Criteria 6.1 both expect an identity lifecycle: provisioned on hire, MFA-protected, deprovisioned on termination, reviewed periodically. Federating SimpleRisk onto the IdP is auditable; maintaining the lifecycle in twelve apps in parallel is theatre.
## Prerequisites
- The **Authentication Extra** activated from the Settings Hub → **Extras** chip → **Custom Authentication** tile. Activation auto-generates a per-install SP certificate and a SimpleSAMLphp `secretsalt`; both are reused across upgrades.
- An admin SimpleRisk account. The configuration page is gated by the `admin` permission.
- Admin access to the IdP you intend to federate with, with rights to register a new SAML application.
- **A test user with a working local SimpleRisk password.** This is the lockout-prevention key. SimpleRisk doesn't *replace* the local login form when SAML is on — both auth paths run side-by-side — but if you accidentally disable a misconfigured admin account, or treat the SSO link as your only entry point, you're stranded. Keep at least one human's local password working until the round-trip is confirmed end-to-end.
- An answer to "what role and team should new users land in?" if you intend to use just-in-time (JIT) provisioning. Without sensible defaults, JIT creates a thousand SimpleRisk accounts with read-only access and no team, and you spend the next month fixing them.
## Step-by-step
### 1. Open the SAML configuration tab
Sign in as an admin and open the Settings cog (top-right of any page) → Settings Hub → **Extras** chip. The catalog shows **Custom Authentication** as an Active tile — click it to open the management page (titled *Custom Authentication Extra* in the breadcrumb). Three tabs sit at the top: **Settings**, **LDAP**, **SAML**. Open the **SAML** tab.
### 2. Capture the SP metadata SimpleRisk hands to your IdP
The first card on the SAML tab is **Service Provider (SP)**. It shows the SP metadata URL, the SP certificate status, and a **Download SP Metadata** button. The metadata URL is derived from the **SimpleRisk Base URL** setting and looks like:
```
https://{your-simplerisk-host}/vendor/simplesamlphp/simplesamlphp/public/module.php/saml/sp/metadata/default-sp
```
Replace `{your-simplerisk-host}` with your instance's hostname (for example, `grc.example.com`). When you send the address to your IdP team or paste it into a ticket, send the whole thing, starting with `https://` and your hostname. A path on its own (`/vendor/simplesamlphp/...`) isn't an address, and a form that drops the placeholder leaves something that looks like a URL but points nowhere. The simplest way to avoid the problem is to copy the URL straight from the **Service Provider (SP)** card, where SimpleRisk has already filled in your host.
This address serves the metadata file. Your IdP's entity ID for SimpleRisk is the one written inside that file, so register the downloaded metadata (or the entity ID it contains) rather than typing this address in as the entity ID.
Older SimpleRisk releases published this address with `/www/` in place of `/public/`. If your IdP was registered with the older address, SimpleRisk still accepts sign-in responses sent to it, but the sign-in request it sends to your IdP names the `/public/` address, and some IdPs (Microsoft Entra ID reports AADSTS50011) refuse a request whose reply URL is not the registered one. SimpleRisk can be switched to advertise the older `/www/` address for the reply URL, and separately for the SP entity ID if that is also registered in the older form; ask SimpleRisk support to make that change for your instance. Use the `/public/` address for any new registration.
If **SimpleRisk Base URL** isn't set or is wrong, fix it first (Settings cog → Settings Hub → **Security** tile); every SAML round-trip depends on it. Click **Download SP Metadata** to save the XML, or copy the URL — most modern IdPs accept either form.
The **SP name** field defaults to `default-sp` and is part of the metadata URL. Leave the default unless you need multiple SP registrations against the same IdP. Changing the SP name after the IdP is configured invalidates the trust and forces a re-upload.
### 3. Register SimpleRisk as an application at your IdP
This half of the round-trip happens *outside* SimpleRisk. The pattern is consistent across IdPs: create a new SAML 2.0 application, upload SimpleRisk's SP metadata, then capture the IdP's metadata URL or XML for the next step.
A few IdP-specific notes:
- **Okta** — upload the SP metadata XML rather than entering ACS URL and audience by hand; the round-trip is more reliable that way.
- **Microsoft Entra ID / ADFS** — both reject AuthnRequests that include the `{Scoping}` element. You must tick **Disable scoping (ADFS / Entra ID compatibility)** in step 6. This is the single most common Entra-with-SimpleRisk gotcha.
- **Google Workspace** — set NameID format to **Email address** in step 4 and match SimpleRisk usernames to the IdP-side primary email.
Whichever IdP you're using, copy its SAML metadata URL (or download the XML) before moving on.
### 4. Paste IdP metadata back into SimpleRisk
In the **Identity Provider (IdP)** card, pick a **Metadata source**:
- **Fetch from URL** — paste the IdP's metadata URL into **Metadata URL**. SimpleRisk re-fetches on the schedule set by **Metadata cache TTL (seconds)** (default 3600). When the URL is unreachable on refresh, the cached copy keeps working. Use **Clear cached metadata now** to force the next login to re-fetch.
- **Paste XML** — paste the IdP's metadata XML directly. Useful when the IdP doesn't expose a public metadata URL.
- **Upload XML file** — same, from a file. SimpleRisk validates well-formedness and rejects DOCTYPE declarations as XXE hardening.
Set **NameID format** to match what the IdP issues. **Let IdP decide (recommended)** is the right starting point. **Email address** suits Google Workspace; **Persistent** is the right choice when you want SimpleRisk to map the same user across sessions regardless of email changes. Avoid **Transient** unless you specifically need it — transient NameIDs change every session and force attribute-based matching instead, which the page surfaces with an inline warning when you select it.
**Trusted redirect domains** is a comma-separated allow-list of domains SimpleRisk accepts as post-authentication redirect targets. It defaults to `sts.windows.net, login.windows.net, dev.simplerisk.com`. Add any IdP-side redirect domain not on the list.
### 5. Map IdP attributes to SimpleRisk fields
The **User Attribute Mapping** card is where most setups go wrong on the first try.
- **Username match** — pick **Authenticated username (NameID)** when the IdP's NameID *is* the SimpleRisk username. Pick **Authenticated attribute** when SimpleRisk should look at a specific SAML attribute instead (required for Transient NameID, or any opaque NameID). When you pick the attribute path, the **Username attribute** field appears — fill in the attribute name (commonly `mail`, `uid`, `userPrincipalName`, or `sAMAccountName`; the field has a datalist).
- **Display name attribute**, **Email attribute**, **Manager username attribute** — the SAML attribute names that populate those SimpleRisk user fields. Leave blank to skip. Names are case-sensitive: `displayName` is not the same as `displayname`.
- **Role attribute**, **Teams attribute** — the SAML attribute names whose *values* identify which SimpleRisk role and team(s) a user belongs to. After saving, the **Mapping** button next to each opens a modal where you map the *remote* role/team names from the IdP to SimpleRisk's local roles and teams. SimpleRisk doesn't auto-create roles; the modal is where the IdP-side `engineering-admins` group becomes the SimpleRisk-side **Engineering Admins** role.
How a login is applied to a user who already exists (it only applies when **Update user with data from the idP** is on):
- **Several role values.** An IdP can send more than one role value for a user. SimpleRisk records every value so you can map it, then gives the user the role of the *first* value, in the order the IdP sends them, that is mapped to a SimpleRisk role. A value you haven't mapped is skipped rather than ending the search. SimpleRisk has no ranking between roles, so if a user can belong to several mapped groups, make sure the IdP sends the lowest-privilege one first or map only the groups you want to count.
- **Attribute missing from the login.** If the IdP leaves the configured role or teams attribute out of a login entirely, what happens depends on **Keep the user's current role and teams when the IdP does not send the role or teams attribute** on the **Settings** tab. It is off by default, so the user falls back to the default role and no teams (the same as a brand-new user). Turn it on if your IdP omits the attribute for users who should keep their access (Microsoft Entra does this for a user who has no App Role assignment): the user then keeps their current role, permissions and teams, and a warning is written to the log on each such login. Leave it off if you rely on removing someone from every group at the IdP to take their access away, because an IdP that omits the attribute for a user in no groups looks exactly like that, and with the setting on that user would keep their access until you change them in SimpleRisk.
- **Attribute sent, but nothing maps.** If the attribute is present and none of its values is mapped, the user falls back to the default role and no teams, the same as a new user. That is how removal from every mapped group takes access away.
For just-in-time (JIT) provisioning, the underlying flag is `AUTHENTICATION_ADD_NEW_USERS` on the **Settings** tab. Set it (along with default role and team) *before* going live or you'll churn through manual user fixups.
### 6. Set authentication behavior
The **Authentication Behavior** card carries the round-trip toggles:
- **Show the "Go to SSO Login Page" link on the main login page** — the visible *Go to SSO Login Page* link on `/index.php`. Leave this off until your test round-trip works.
- **Force authentication on every login** — sends `ForceAuthn=true` in every request, bypassing any existing IdP session. Useful for kiosks; otherwise leave off.
- **Logout terminates SimpleRisk session AND logs user out of the SAML Identity Provider (IdP)** — initiates SAML Single Logout (SLO) on logout. SLO is fragile; if you see logout loops, turn this off.
- **Require signed assertions** — recommended on. Virtually every production IdP signs assertions.
- **Disable scoping (ADFS / Entra ID compatibility)** — required for Microsoft ADFS and Entra ID, which reject requests with the `{Scoping}` element.
- **Sign authentication requests** / **Require encrypted assertions** — these only appear when the SP certificate is configured (auto-generated on Extra activation). Enable each only after the IdP-side change is in place; enabling early breaks login.
Click **Update** to save.
### 7. Test the round-trip without locking yourself out
SimpleRisk doesn't ship a discrete test/enforce toggle. The pattern is structural: leave the SSO link on the main login page **off** during testing, drive your test user to the SSO URL directly, and only flip the link on once the round-trip works. The SSO login URL is:
```
https://{your-simplerisk-host}/extras/authentication/login.php
```
As with the metadata address, `{your-simplerisk-host}` is your instance's hostname, so the full address for an instance at `grc.example.com` is `https://grc.example.com/extras/authentication/login.php`. Hand that URL to a test user with a matching IdP account. You should see a redirect to the IdP, IdP login (or session reuse), redirect back, and a landing on the SimpleRisk reports page. The debug log captures every step — `SAML user was successfully authenticated by the IdP.` confirms the IdP side worked. If you don't see that line, look immediately above for `SAML authentication failed:` or `SAML user was not authenticated by the IdP.`; the message after the colon is the IdP's complaint and the starting point for debugging.
Your own admin account stays on the main login form at `/index.php` with its local password while you test. That's the lockout-recovery path. Don't disable that account.
### 8. Activate SSO for production
When the test round-trip is clean (including role and team mapping if you use them), tick **Show the "Go to SSO Login Page" link on the main login page** and click **Update**. Users visiting `/index.php` now see a *Go to SSO Login Page* link below the password fields. The local form remains visible; SimpleRisk does not have an enforce-SSO mode that hides it.
## Verifying the configuration
Three signals confirm a healthy setup:
- A clean round-trip from `/extras/authentication/login.php` — IdP redirect, IdP sign-in, redirect back, landed on the SimpleRisk reports page as the right user with the right role and teams.
- The debug log shows `SAML user was successfully authenticated by the IdP.` followed by `Granting access for UID " " USERNAME "{name}".` (both at `info` level). If you see `Not a valid SAML user in SimpleRisk.` instead, either the user doesn't exist locally and JIT isn't on, or the username matching rule isn't picking up the right attribute.
- The audit log records `Custom Authentication Extra was toggled on by username "{admin}".` in the audit trail when activation happened — useful evidence in an access-management audit that the change is documented and dated.
## Troubleshooting
> **If you're locked out by a SAML misconfiguration:** SAML doesn't replace local auth in SimpleRisk. Go to `https://{your-simplerisk-host}/index.php` — the local login form is always shown, and SAML-on does not disable local password authentication. Sign in there with any local-password admin account and fix the SAML config. Database surgery on the `user` table is the last resort, only needed if every local password is gone.
When the identity provider's response is rejected — a mismatched destination, a missing or invalid signature, an unknown issuer, an expired assertion — the user sees a "Sign-in could not be completed" page with a reference number and a link back to the login page, and the server answers with an HTTP 400 or 401 status rather than a server error. Any other SAML failure still dies on the SimpleSAMLphp error page — "Unhandled exception" plus a tracking number. In both cases the real reason is in the web server's error log, not on screen. Search the log for the tracking number; the `Caused by:` line names the actual exception. For example, `Received unencrypted assertion, but encryption was enabled.` means **Require encrypted assertions** is ticked but the IdP isn't encrypting. Releases after 20260519-001 log this detail automatically. On older versions it's suppressed: edit `simplerisk/vendor/simplesamlphp/simplesamlphp/config/config.php`, set `'backtraces' => true` inside the `'debug'` array, and reproduce the login once.
The handful of failure modes that drive most SAML support traffic.
- **Clock skew on assertion timestamps.** SAML assertions carry `NotBefore` / `NotOnOrAfter` timestamps signed by the IdP. SimpleRisk's host clock has to be inside that window. NTP drift of more than a few minutes produces "assertion is not yet valid" or "assertion has expired" errors. Fix the clock; never widen the tolerance.
- **Certificate format issues.** SAML certificates are PEM-encoded — base64 between `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. If the IdP exports DER (binary), convert it: `openssl x509 -inform DER -in idp.cer -out idp.pem`. Pasting raw base64 without the PEM header lines produces opaque "could not parse certificate" errors.
- **Attribute mapping mismatches (case sensitivity).** SAML attribute names are case-sensitive at the wire level. `mail` and `Mail` are different attributes. To see exactly what the IdP sends, enable `debug` log level temporarily and look for the `SAML Attributes provided by the IdP:` line — the array dump shows the attribute names verbatim.
- **Circular redirect loops on Single Logout.** SLO is the most fragile part of SAML. If the IdP can't process an SLO request, the user bounces, SimpleRisk re-issues, the IdP rejects again, loop. The fix is to turn off **Logout terminates SimpleRisk session AND logs user out of the SAML Identity Provider (IdP)**. SimpleRisk-side logout still works; it just doesn't try to take down the IdP session as well.
- **Microsoft ADFS or Entra ID rejects AuthnRequests.** Tick **Disable scoping (ADFS / Entra ID compatibility)** and retest.
- **Missing PHP extensions on minimal or hardened builds.** SimpleSAMLphp needs PHP extensions that SimpleRisk Core does not: `tokenizer`, `openssl`, `simplexml`, `libxml`, `session`, `ctype`, `filter`, and `fileinfo`. A missing one fails every SAML request with a generic "Unhandled exception" page. SUSE is the usual culprit — it splits these into separate packages (`zypper install php8-tokenizer`), where Debian and RHEL bundle them. The **Health Check** page in the admin settings flags any missing extension once the Extra is installed.
- **The SP certificate is about to expire.** The page surfaces a colored badge with days remaining; under 30 days it goes red. Use **Regenerate** to issue a fresh self-signed cert (RSA-2048, 10-year validity), then re-upload SP metadata to the IdP. Logins fail in the window between regeneration and IdP pickup — schedule the change.
## Related
- [The Authentication Extra Overview](https://support.simplerisk.com/kb/04-03-the-authentication-extra-overview?hsLang=en)
- [Multi-Factor Authentication](https://support.simplerisk.com/kb/04-02-multi-factor-authentication?hsLang=en)
- [OIDC Setup](https://support.simplerisk.com/kb/04-05-oidc-setup?hsLang=en)
- [Local Authentication and Password Policies](https://support.simplerisk.com/kb/04-01-local-authentication-and-password-policies?hsLang=en)
- [FAQs](https://support.simplerisk.com/kb/faqs?hsLang=en)
- [SimpleRisk Extras](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#main-content)
- [Vulnerability Management Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#vulnerability-management-extra)
- [Team Separation Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#team-separation-extra)
- [Import-Export Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#import-export-extra)
- [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#main-content)
- [00 About This Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#00-about-this-guide)
- [01 Installation and Deployment](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#01-installation-and-deployment)
- [02 Upgrades and Maintenance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#02-upgrades-and-maintenance)
- [03 Users and Permissions](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#03-users-and-permissions)
- [04 Authentication](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#04-authentication)
- [05 Customization](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#05-customization)
- [06 Configuring Risk and Compliance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#06-configuring-risk-and-compliance)
- [07 Integrations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#07-integrations)
- [08 The API](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#08-the-api)
- [09 Encryption and Data Security](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#09-encryption-and-data-security)
- [10 Workflows and Automation](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#10-workflows-and-automation)
- [11 Reporting and Auditing](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#11-reporting-and-auditing)
- [12 Operations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#12-operations)
- [13 Reference](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#13-reference)
- [User Guide](https://support.simplerisk.com/kb/user-guide?hsLang=en#main-content)
- [00 Foundations of GRC](https://support.simplerisk.com/kb/user-guide?hsLang=en#00-foundations-of-grc)
- [01 Risk Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#01-risk-management)
- [02 Compliance Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#02-compliance-management)
- [03 Governance](https://support.simplerisk.com/kb/user-guide?hsLang=en#03-governance)
- [04 Asset and Data Inventory](https://support.simplerisk.com/kb/user-guide?hsLang=en#04-asset-and-data-inventory)
- [05 Threat and Vulnerability Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#05-threat-and-vulnerability-management)
- [06 Assessments](https://support.simplerisk.com/kb/user-guide?hsLang=en#06-assessments)
- [07 Incident Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#07-incident-management)
- [08 Audit and Reporting](https://support.simplerisk.com/kb/user-guide?hsLang=en#08-audit-and-reporting)
- [09 Day-to-Day SimpleRisk](https://support.simplerisk.com/kb/user-guide?hsLang=en#09-day-to-day-simplerisk)
- [10 Continuous Improvement](https://support.simplerisk.com/kb/user-guide?hsLang=en#10-continuous-improvement)
- [SimpleRisk User Guides](https://support.simplerisk.com/kb/simplerisk-user-guides?hsLang=en)
- [Troubleshooting](https://support.simplerisk.com/kb/troubleshooting?hsLang=en)
- [SimpleRisk Hosted](https://support.simplerisk.com/kb/simplerisk-hosted?hsLang=en)
- [How To videos](https://support.simplerisk.com/kb/how-to-videos?hsLang=en)
[](https://www.simplerisk.com)
Copyright © 2026, SimpleRisk, Inc.