Connection status

What each status does to new logins and sessions. What the error policy changes. How to set both.

Setting a connection to inactive stops new logins through it. The sign-in service itself refuses them, not only the RealmSSO screens. Existing sessions keep working. Live now · API and dashboard.

This page answers one question: do existing connections still work after a status change? Their sessions do. Their new logins depend on the status. An integration test against a running sign-in service covers the rules for inactive connections and for existing sessions.

Four words

Word	Meaning	What a status change does to it
Configuration	The connection record and its entry in the realm.	Keeps it. The entry stays. RealmSSO only switches the entry on or off.
Brokering new logins	The realm accepts a new login through the connection and passes the sign-in through to your customer’s IdP.	The status decides it.
Existing session	A user signed in through the connection earlier and still holds a session in the realm.	Does not touch it. The session runs until it expires.
In-flight login	A login that has started and has not finished.	Makes no promise about it.

Which status lets a login through?

Status	Who sets it	New logins	Existing sessions
`active`	You, or RealmSSO after a create or an edit that works.	Pass through.	Not touched.
`inactive`	You.	Refused. No option softens this.	Not ended.
`error`	RealmSSO, when it cannot create the entry or cannot change it.	The account policy decides. They pass through under `fail_open`, the default. They are refused under `fail_closed`.	Not ended.
`pending`	RealmSSO, while it creates the connection.	Refused.	Not ended.

A PATCH accepts active, inactive and error. RealmSSO sets pending itself. A status that RealmSSO does not know never passes a login through.

What inactive does

RealmSSO switches the entry of the connection off in the realm. The sign-in service then ignores requests that name the connection. It also hides the connection from its sign-in page. The stop happens in the sign-in service, not only in the RealmSSO screens.

GET /api/v1/connections/:id/initiate also refuses the connection. It answers 403 with the code CONNECTION_NOT_BROKERING, before it builds any URL.

{
  "error": {
    "code": "CONNECTION_NOT_BROKERING",
    "message": "This SSO connection is inactive, so it does not accept new logins. Existing sessions are unaffected. Ask your administrator to set the connection back to active.",
    "details": { "connectionId": "<connection-id>", "status": "inactive", "reason": "inactive" }
  }
}

The reason is inactive, error_fail_closed or unknown_status. A connection in pending has the reason unknown_status.

The error policy never changes inactive. The configuration stays. Nothing is deleted. Setting the status back to active turns new logins on again.

What error does

RealmSSO sets error when it cannot create the entry, or cannot change it after an edit. The metadata field of the connection holds the reason in provisionError. A create that fails after the entry exists also lands in error. error reports a failure of a RealmSSO change. It is not an instruction from you.

Policy	New logins through a connection in error
`fail_open` (default)	Pass through, with the configuration that the entry holds now. The error stays visible on the connection and in the audit log.
`fail_closed`	Refused, as for inactive. They stay refused until you save the connection again with success, or set it to active.

Which configuration does the entry hold? After a failed edit, it is usually the previous one. RealmSSO checks the new settings before it replaces the entry, so a bad setting leaves the old entry in place. A failure after the replacement leaves the new entry live. After a failed create, the entry holds the settings it was just created with. If no entry exists, no login passes under either policy.

The tradeoff of fail_open: logins continue against a configuration that RealmSSO could not confirm. The tradeoff of fail_closed: a failed change stops new logins through that connection until someone fixes it.

Change the error policy

Only an account admin can change the policy. A member or a viewer gets 403. An API key cannot call the route. A viewer can read the current policy in the connectionErrorPolicy field of GET /api/v1/accounts/:id.

API=https://api.realmsso.com
curl -X POST "$API/api/v1/accounts/<account-id>/connection-error-policy" \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"policy":"fail_closed"}'

The body takes policy: fail_open or fail_closed. The change re-evaluates every connection of the account that is in error now, in the same request. It does not touch a connection in active or inactive. It ends no session.

{
  "data": { "id": "<account-id>", "connectionErrorPolicy": "fail_closed" },
  "reevaluated": [
    { "connectionId": "<connection-id>", "brokering": false, "outcome": "enforced" }
  ]
}

Other account fields are left out of this example. The dashboard account page has a Connection error policy card. It has the two choices and a Save policy button. A policy change moves no status, so it sends no webhook event. Read the response instead.

What does not change

A status change or a policy change ends no session. The brokering report and the audit row say so with sessionsTerminated: false. A user who signed in an hour ago stays signed in until the session expires. A status change makes no promise about a login that is already in flight.

Deleting a connection is different

Deleting a connection ends the sessions of every user who signed in through it. RealmSSO ends them first. If it cannot end the sessions of one user, it logs a warning and goes on. Then it deletes the entry, and last it deletes the record. See Connections.

The brokering report

A PATCH on a connection returns the connection in data and a brokering report. A save in the Admin Portal runs the same step. It returns only the connection.

{
  "data": { "id": "<connection-id>", "status": "inactive" },
  "brokering": {
    "brokering": false,
    "reason": "inactive",
    "outcome": "enforced",
    "sessionsTerminated": false
  }
}

Other connection fields are left out of this example.

Field	Meaning
`brokering`	True when the connection accepts new logins.
`reason`	The rule that decided it: `active`, `error_fail_open`, `inactive`, `error_fail_closed` or `unknown_status`.
`outcome`	Whether the sign-in service now agrees. See the next table.
`sessionsTerminated`	Always `false`.
`warning`	A text. It is present only when someone must act.

Outcome	Meaning
`enforced`	The sign-in service now matches the decision.
`no_idp`	The connection has no entry in the realm, so nothing passes logins through. Save the IdP settings again to create the entry. A rename or a status change alone does not create it.
`restricted_beyond_row`	RealmSSO could not switch logins back on. Logins stay refused. This is the safe direction. Send the request again.
`diverged_brokering`	RealmSSO could not switch logins off. The sign-in service may still accept new logins. The route answers 502.

When the sign-in service cannot be changed

RealmSSO does not report success when it cannot stop new logins in the sign-in service. A PATCH or a portal save answers 502 with the code CONNECTION_STATUS_ENFORCEMENT_INCOMPLETE. The policy route answers 502 with the code CONNECTION_ERROR_POLICY_ENFORCEMENT_INCOMPLETE.

RealmSSO keeps the new status or policy. Its own initiate route already refuses the connection. The sign-in service may still accept new logins until a retry works. Send the same request again. It is safe to repeat.

Edit a connection and its status

An edit of the IdP settings re-provisions the entry: in place when the upstream identity stays the same, replaced when it changes. See Connections. The status after the edit follows these rules.

An edit that works: the status is the one named in the request. If the request names none, an inactive connection stays inactive. Any other connection becomes active. This clears error.
An edit that fails: the status is inactive when the request names inactive. It is also inactive when the request names no status and the connection is inactive. Any other connection becomes error.
RealmSSO then applies the rules in the status table. A failed edit never switches logins back on for an inactive connection.

Where you reach it

What	API	Dashboard
Set the status of a connection	`PATCH /api/v1/connections/:id` with `status`. Role `member`.	The connection page: Activate and Deactivate.
Set the error policy	`POST /api/v1/accounts/:id/connection-error-policy`. Role `admin`. Dashboard session only.	The account page: the Connection error policy card.
Read the status	`GET /api/v1/connections/:id`, field `status`.	The connection page shows the status.

The Admin Portal shows the status and the last recorded health. It has no switch for status. A save in the portal can still move a connection to error, and the same rules apply.

Webhook event

The event connection.status.changed fires when a status changes. It fires from five paths:

The connections PATCH.
The SAML create and the OIDC create, through the API or the Admin Portal.
The SAML save and the OIDC save in the Admin Portal.

The event carries connectionId, accountId, previousStatus, status and changedAt. It does not fire when the status stays the same. One event exists today. See Webhooks API.

← Connections SCIM directory sync →