# Sandbox and test IdP

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](/get-started/claimable-sandboxes/) creates a temporary test environment without an account. An unclaimed sandbox is deleted, with nothing recoverable, 7 days after its creation.

## 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 /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](/get-started/quickstart-init/#a-test-connection-from-the-api). Where an environment has no test IdP, that call answers 503 [`service_unavailable`](/errors/service_unavailable/); use an identity provider you control instead.

## 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`](/errors/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](#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](#test-controls-on-the-connection-test) of `POST /v1/connections/{connection}/test`.

## Test controls on the 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](#scenarios).                                                                          |
| `time_shift`  | A Go duration such as `-10m` or `2h`, at most 24 hours either way. See [shifting the clock](#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`](/errors/sandbox_required/); on a sandbox connection to any other IdP it answers 400 [`parameter_invalid`](/errors/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](/reference/api/management/).

## 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`](/errors/email_outside_verified_domain/)                                                      | [`email_outside_verified_domain`](/errors/email_outside_verified_domain/)                              |
| `bad_signature`  | [`saml_signature_invalid`](/errors/saml_signature_invalid/)                                                                    | [`oidc_id_token_invalid`](/errors/oidc_id_token_invalid/)                                              |
| `expired`        | [`saml_response_expired`](/errors/saml_response_expired/)                                                                      | [`oidc_id_token_invalid`](/errors/oidc_id_token_invalid/)                                              |
| `wrong_audience` | [`saml_audience_mismatch`](/errors/saml_audience_mismatch/)                                                                    | [`oidc_id_token_invalid`](/errors/oidc_id_token_invalid/)                                              |
| `missing_email`  | [`saml_email_missing`](/errors/saml_email_missing/)                                                                            | [`oidc_email_missing`](/errors/oidc_email_missing/)                                                    |
| `rotated_cert`   | [`saml_signature_invalid`](/errors/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`](/errors/saml_idp_status_error/), from a signed `Responder` status with no assertion.                 | [`oidc_token_exchange_failed`](/errors/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

`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`](/errors/saml_response_expired/) or [`saml_response_not_yet_valid`](/errors/saml_response_not_yet_valid/) for SAML, [`oidc_id_token_invalid`](/errors/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`.

## 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

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`](/errors/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.

## 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](/tools/scim-tester/).

## 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](/sso/how-it-works/) for the application flow and [SCIM concepts](/directory-sync/scim-concepts/) for provisioning.
