IdP failure modes, MFA & debugger

A sign-in that works proves only the happy path. The mock identity providers can also send the responses a careful app must refuse, ask for a second factor, and validate their own answers in a built-in debugger:

• Failure modes make the IdP send expired, misaddressed, incomplete or failing responses, so you can check that your app rejects them.
• MFA and step-up add a simulated one-time-code step, with amr, acr, auth_time and max_age in OIDC and AuthnContextClassRef in SAML.
• The debugger signs in the way a strict relying party would and lists every check it made.

These work on every plan. They apply to generic OIDC and SAML IdPs; the social login presets have their own failure modes.

#Failure modes

A fault only changes ordinary fields (claims, times, audience, destination, status) before the normal signing step, so responses stay signed by the IdP's own key. The one exception is the SAML unsigned fault, which leaves out every signature. The IdP never forges or tampers with a signature.

A fault is chosen for each sign-in, in this order:

1. The Sign in with select next to each user on the login screen (normal or a fault).
2. ?fault=<id> on the authorize URL (OIDC) or the SSO URL (SAML), for automated tests. ?fault=none turns the default off for one sign-in. An unknown ID is an invalid_request error (OIDC) or an error page (SAML).
3. The IdP's default failure mode, on the Setup tab or with PATCH /api/idps/:id and faults. A default that exists for only one protocol leaves the other protocol's sign-ins normal.

With auto-login there is no login screen, so only 2 and 3 apply. The fault travels with the authorization code and refresh token, so token-endpoint and userinfo faults hit the requests that follow the sign-in. Every activity-log event of a faulted sign-in has details.fault and a fault badge.

# Every sign-in of this IdP gets an expired ID token until you switch it off
curl -X PATCH https://app.testlie.com/api/idps/$IDP_ID \
  -H "Authorization: Bearer $TESTLIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "faults": { "mode": "expired_id_token" } }'

# Back to normal
curl -X PATCH https://app.testlie.com/api/idps/$IDP_ID \
  -H "Authorization: Bearer $TESTLIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "faults": { "mode": null } }'

Two faults take a parameter, set with faults: skewSeconds (default 300, at most 86,400) is how far not_yet_valid moves times into the future, and delayMs (default 10,000, at most 30,000) is how long slow_token waits.

#OIDC

#SAML

#In an end-to-end test

Set the IdP's default failure mode before the test, run your sign-in flow, assert that your app shows its error and created no session, then clear the default. If your test controls the authorize URL, add &fault=<id> to it instead, so tests with different faults can run in parallel.

const setFault = (mode) =>
  fetch(`${TESTLIE}/api/idps/${IDP_ID}`, {
    method: "PATCH",
    headers: { Authorization: `Bearer ${TESTLIE_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ faults: { mode } }),
  });

test("rejects an ID token for another audience", async () => {
  await setFault("wrong_audience");
  try {
    // ... sign in through your app and expect its error page ...
  } finally {
    await setFault(null);
  }
});

#MFA and step-up

The Multi-factor step setting (Setup tab, or mfa in PATCH /api/idps/:id) decides when the IdP asks for a one-time code after the user is picked:

Values that ask for MFA: mfa, otp, phr, phrh, http://schemas.openid.net/pape/policies/2007/06/multi-factor, urn:okta:loa:2fa:any, urn:okta:loa:2fa:any:ifpossible, urn:oasis:names:tc:SAML:2.0:ac:classes:MultiFactor, urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract, urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken and http://schemas.microsoft.com/claims/multipleauthn.

On the code screen any six digits pass. 000000 simulates a failed challenge: OIDC returns error=access_denied with a description, and SAML posts a Responder / AuthnFailed status. Auto-login completes the step on its own and still reports MFA.

What the IdP reports:

A correct app compares acr with what it asked for: when the setting is off, a request for mfa comes back as acr: "pwd", and the app must refuse the step-up.

max_age (any value) and prompt=login force a fresh sign-in, so the login screen is shown even with an auto-login user; SAML ForceAuthn="true" does the same. prompt=none with max_age=0 returns login_required.

#The debugger

Test OIDC and Test SAML on the IdP's page (and Try in OIDC debugger and Try in SAML debugger in the Failure modes card) start a sign-in from https://app.testlie.com/idp/<slug>/debug/start. Like a real app, the debugger first stores state and nonce (OIDC) or the AuthnRequest ID (SAML) in a session tied to a cookie, then validates the answer completely and lists each check as PASS or FAIL. It allows 60 seconds of clock leeway.

Start parameters:

The debugger is always an allowed redirect URI and ACS URL, so it needs no setup. Each check on the result page has a stable ID (data-check="<id>" and data-ok="true" or "false"), so a browser test can assert on it.

Use the debugger to see what a fault looks like before you test your app with it: a fault that makes a debugger check fail is a response your app must refuse too.