Skip to content
Dashboard
Theme
Theme

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.

View Markdown

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.

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 /v1/connections/{connection}/test 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 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 /v1/connections/{connection}/test.

POST /v1/connections/{connection}/test 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.

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.

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 /v1/connections/{connection}/test.

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.

These steps run in a sandbox only. Each test is a POST /v1/connections/{connection}/test 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.

  1. Configure a SAML connection to the test IdP from /saml/metadata?cert=current, run its test with sp_initiated and activate it.
  2. Run a test with "certificate": "rotated" (or the rotated_cert scenario). It fails with saml_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.
  3. Update the connection from /saml/metadata?cert=rollover. Test with "certificate": "current" and with "certificate": "rotated"; both succeed, because the connection trusts both certificates.
  4. Update the connection from /saml/metadata?cert=rotated. "certificate": "rotated" succeeds, and "certificate": "current", still signed with the old key, now fails with saml_signature_invalid. The rollover is complete.
  5. To rehearse expiry instead, configure the connection from /saml/metadata?cert=expiring and test with "certificate": "expiring" (or the expiring_cert scenario). The sign-in succeeds, and the connection’s certificate, which expires within the seven-day alert window, raises the expiry alerts.

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.

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.