Sandbox and test IdP
Test sign-ins in a sandbox against the test IdP, pick failure scenarios, shift its clock and rehearse a certificate rollover.
Use a sandbox environment for development and a separate production environment for customer traffic. Keys and resources are scoped to their environment; do not move sandbox object IDs or credentials into production.
The claimable sandbox API creates a temporary test environment without an account. An unclaimed sandbox is deleted, with nothing recoverable, 7 days after its creation.
Testing a connection
Section titled “Testing a connection”Register the exact callback URI. Localhost callbacks are allowed only in sandbox; production redirects require the production allow-list. Configure a connection, verify an organization domain, run its test and activate it before trying the application sign-in flow.
POST / returns a test URL and expiry. The ticket lasts 15 minutes and is single-use. It completes on a test result page and records success or failure, never an application authorization code. Draft and errored connections cannot start a test. Passing a test is required before activation.
POST /v1/dev/init with "test_connection": true, or ohauthcat init in the CLI, creates a sandbox test organization with a SAML connection to the test IdP and returns a one-time test URL. See Quickstart: ohauthcat init. Where an environment has no test IdP, that call answers 503 service_unavailable; use an identity provider you control instead.
The test IdP
Section titled “The test IdP”The test IdP is a SAML 2.0 and OIDC identity provider run by OhAuthCat for sandbox environments only. It refuses every relying party outside a sandbox with 403 sandbox_required, before it reads any scenario or time shift, so none of these controls can reach a production environment. It issues identities only on its own reserved domain, never on yours.
When a sign-in reaches it, the test IdP shows a picker:
| Field | Meaning |
|---|---|
| User | A lowercase local part, such as alice. The domain is always the test IdP’s own. |
| IdP flavor | Which IdP’s attribute and NameID conventions to imitate, such as okta. |
| Scenario | The outcome to produce, from the table below. The default is sp_initiated. |
| Time travel | Optional time_shift, such as -10m or 2h. See shifting the clock. |
The picker sends user, profile, scenario and time_shift. The same names, plus cert (current, rotated or expiring, the key the test IdP signs with), are accepted as query or form parameters on the test IdP’s sign-in endpoints. To set them from your own code, use the test controls of POST /.
Test controls on the connection test
Section titled “Test controls on the connection test”POST / takes three optional body fields that are passed to the test IdP with the test sign-in:
| Field | Values |
|---|---|
scenario |
One of the scenario names. |
time_shift |
A Go duration such as -10m or 2h, at most 24 hours either way. See shifting the clock. |
certificate |
current, rotated or expiring: the key the test IdP signs with, for any scenario. |
The controls work only on a connection to the test IdP in a sandbox environment. In a production environment the call answers 400 sandbox_required; on a sandbox connection to any other IdP it answers 400 parameter_invalid. A malformed value, such as an unknown scenario or a shift over 24 hours, also answers parameter_invalid.
With the rotated_cert or expiring_cert scenario, certificate is optional, but if you send it, it must name that scenario’s key (rotated or expiring); any other value answers parameter_invalid.
For example, the body {"scenario": "sp_initiated", "time_shift": "-10m", "certificate": "rotated"} asks the test IdP for a normal response, signed with the rotated key and dated ten minutes in the past. The response is the usual test URL and expiry.
See the management reference.
Scenarios
Section titled “Scenarios”Each scenario produces a real, signed response. OhAuthCat’s broker checks it exactly as it checks a customer IdP’s response; the test IdP never relaxes a check, it only gives the broker something to refuse.
| Scenario | What the test IdP sends |
|---|---|
sp_initiated |
A normal response to your sign-in request. |
idp_initiated |
An unsolicited response, with no request to answer. |
guest_domain |
A user on a domain the organization has not verified. |
bad_signature |
A response with a broken signature. |
expired |
A response past its validity window. |
wrong_audience |
A response addressed to another service provider. |
missing_email |
A user with no email address. |
rotated_cert |
A response signed with the test IdP’s rotated key. |
expiring_cert |
A response signed with a key whose certificate expires in five days. |
revoked_user |
A refusal for a user whose access the IdP revoked. |
What the broker answers for each:
| Scenario | SAML result | OIDC result |
|---|---|---|
sp_initiated |
Success. | Success. |
idp_initiated |
Success where the connection allows IdP-initiated sign-in. | Refused by the test IdP; OIDC has no IdP-initiated sign-in. |
guest_domain |
email_outside_verified_domain |
email_outside_verified_domain |
bad_signature |
saml_signature_invalid |
oidc_id_token_invalid |
expired |
saml_response_expired |
oidc_id_token_invalid |
wrong_audience |
saml_audience_mismatch |
oidc_id_token_invalid |
missing_email |
saml_email_missing |
oidc_email_missing |
rotated_cert |
saml_signature_invalid until the connection trusts the rotated certificate, then success. |
Success; the JWKS publishes the rotated key. |
expiring_cert |
Success while the connection trusts that certificate, which then raises its expiry alerts. | Success; the JWKS publishes the expiring key. |
revoked_user |
saml_idp_status_error, from a signed Responder status with no assertion. |
oidc_token_exchange_failed, from an access_denied redirect. |
rotated_cert and expiring_cert need the test IdP’s rotated and expiring keys. Where they are not configured, the test IdP refuses those scenarios instead of signing with another key.
Shifting the clock
Section titled “Shifting the clock”time_shift dates the documents the test IdP issues by that offset: a Go duration such as -10m, 90s or 2h, at most 24 hours either way. It moves the SAML IssueInstant, NotBefore and NotOnOrAfter, and the OIDC iat, exp and auth_time. It never moves OhAuthCat’s validation clock.
A small shift inside the clock-skew allowance still signs in, which is how you check that a slightly wrong IdP clock is tolerated. A larger shift is refused exactly as a real IdP with a wrong clock would be: saml_response_expired or saml_response_not_yet_valid for SAML, oidc_id_token_invalid for OIDC. Set it in the picker, as the time_shift parameter, or in the time_shift field of POST /.
Metadata for each certificate
Section titled “Metadata for each certificate”The test IdP’s SAML metadata is at /saml/metadata on its base URL; the same URL is its entity ID. The cert query parameter chooses which signing certificates the metadata lists:
| Query | Certificates listed | Use it to |
|---|---|---|
?cert=current |
The current key only. The default. | Start from a normal connection. |
?cert=rollover |
The current and the rotated key. | Trust both while a rollover is in progress. |
?cert=rotated |
The rotated key only. | Finish the rollover and drop the old certificate. |
?cert=expiring |
The expiring key only. | Watch the connection’s certificate expiry alerts. |
Any other value, or a set whose key is not configured, answers 400 invalid_request. The OIDC JWKS always lists the current, rotated and expiring keys.
Rehearse a certificate rollover
Section titled “Rehearse a certificate rollover”These steps run in a sandbox only. Each test is a POST / with the body shown; certificate combines with any scenario, so you can also rehearse a failure, such as missing_email, signed with the rotated key. Production environments are refused by the test IdP, and the broker’s signature checks are the same ones your customers’ connections get.
- Configure a SAML connection to the test IdP from
/, run its test withsaml/ metadata? cert=current sp_initiatedand activate it. - Run a test with
"certificate": "rotated"(or therotated_certscenario). It fails withsaml_signature_invalid: the connection does not trust the new certificate yet. This is what your customer sees if their IdP rotates before you update the connection. - Update the connection from
/. Test withsaml/ metadata? cert=rollover "certificate": "current"and with"certificate": "rotated"; both succeed, because the connection trusts both certificates. - Update the connection from
/.saml/ metadata? cert=rotated "certificate": "rotated"succeeds, and"certificate": "current", still signed with the old key, now fails withsaml_signature_invalid. The rollover is complete. - To rehearse expiry instead, configure the connection from
/and test withsaml/ metadata? cert=expiring "certificate": "expiring"(or theexpiring_certscenario). The sign-in succeeds, and the connection’s certificate, which expires within the seven-day alert window, raises the expiry alerts.
SCIM delivery
Section titled “SCIM delivery”The test IdP’s SCIM simulator replays recorded IdP provisioning conversations against a SCIM server, including late deliveries: a delay on every request, or on one step, of at most 10 minutes each, cancellable at any time. It runs in OhAuthCat’s local test harness; there is no hosted endpoint to start a replay yet. To test your own SCIM server’s conformance, use the SCIM tester.
Your own tests
Section titled “Your own tests”Exercise callback state mismatch, expired state, reused codes, wrong organization, webhook tampering, duplicate events and deprovisioning in your own tests. A mock confirms request and response handling; it does not validate your IdP’s configuration or prove hosted availability.
Follow SSO for the application flow and SCIM concepts for provisioning.