Connections

A connection links one account to one identity provider (IdP) of your customer. The IdP is a SAML 2.0 or OIDC provider. A connection is configuration. It is never a session. Not yet tested against Entra ID, Okta, ADFS or Google.

A realm is the separate sign-in space of one account. RealmSSO creates one entry in the realm for each connection. The entry links the realm to your customer's IdP. RealmSSO creates the entry switched off. It switches the entry on only after every step has finished.

The entry has an alias. The alias is saml-<connection-id> for SAML and oidc-<connection-id> for OIDC. It is opaque. It holds no account slug.

Four words

These four words mean the same on every page about connections. A status change acts on the second word only. The API uses the second word too: the brokering report and the code CONNECTION_NOT_BROKERING. See Connection status.

Create a connection

You have four ways to create a connection. The last column says where each way is reached.

The dashboard form takes a metadata URL for SAML. It has no fields for the three manual values. It also shows optional ACS URL and entity ID fields. Leave the ACS URL field empty. In the Admin Portal an IT admin can set up a SAML connection. The OIDC tab of the portal does not work today. Your team sets up OIDC in the dashboard or the API.

SAML from a metadata URL

Send metadataUrl. The sign-in service reads the metadata at that URL and creates the entry. The URL must point to a public address. RealmSSO does not follow redirects. The metadata must hold a signing certificate. If it holds none, RealmSSO sets up no identity provider from it. The request does not return 400: a create returns 201 with the connection in status error and the reason in metadata.provisionError (see When RealmSSO cannot create the entry).

SAML from pasted metadata XML

Send the XML in metadataXml. API only. No screen takes XML, and there is no file upload. The XML must hold an entity ID, a single sign-on endpoint and a signing certificate. The endpoint must use the HTTP-POST or the HTTP-Redirect binding.

If the XML lacks one of these, the request returns 400. It also returns 400 when the endpoint is not a public address. No connection exists then. A connection made from XML has no metadata URL. The on-demand check does not contact the IdP for it.

SAML from three manual values

Send idpEntityId, idpSsoUrl and idpCertificate. All three are required. They describe your customer's IdP. RealmSSO generates the ACS URL and the SP entity ID. Your customer does not enter them here.

OIDC from a discovery URL

Send clientId, clientSecret and discoveryUrl. The sign-in service reads the endpoints from the discovery document. The URL must point to a public address.

When RealmSSO cannot create the entry

A request can pass validation and still fail at the sign-in service. The response is then 201 and the connection has the status error. The metadata field holds the reason in provisionError. A discovery document without an authorization endpoint or a token endpoint ends this way. Metadata at a metadataUrl with no signing certificate ends this way too. A connection in error follows the error policy of the account. See Connection status.

The three values your customer registers

For a SAML connection, your customer registers three values in their IdP. They are the ACS URL, the SP entity ID and the SP descriptor URL. <sign-in-origin> is the scheme and host of the sign-in service. Per-customer hostnames are switched off in production, so the origin is the shared host of the sign-in service.

The realm name kr-<account-id> comes from the account id. It holds no customer name. For an OIDC connection your customer registers one redirect URI: <sign-in-origin>/realms/kr-<account-id>/broker/oidc-<connection-id>/endpoint. The sign-in service exchanges the code. The RealmSSO API is not on the login path. The sign-in service also stores the tokens that your customer's IdP returns at sign-in.

You can read the values in four places. The create response holds ssoConfig. The route GET /api/v1/sso/accounts/:id/config returns customerSetup for each connection, with acsUrl, spEntityId and spMetadataUrl. The dashboard shows them on the SSO client card of the account. The Admin Portal shows the ACS URL and entity ID only after the IT admin saves the IdP details. If you set an acsUrl override,ssoConfig and the Admin Portal show that override instead of the real ACS URL.

Check a connection on demand

POST /api/v1/connections/:id/test checks one connection when you call it. No schedule runs it. The check never performs a login. A passing check does not prove that a login works.

Each check sets healthStatus to healthy or down. It also sets lastHealthCheckAt, and it writes an audit row and an event. RealmSSO never writes degraded. A failed check is a normal 200 response with reachable: false and an error text. You reach the check through the API and the dashboard (Test Connection). The Admin Portal has no connection check.

Certificate expiry

RealmSSO encrypts the SAML signing certificate and the OIDC client secret at rest in its own database. The sign-in service holds its own working copy of each. RealmSSO records the expiry date of the certificate when it creates or changes the entry. The check and the config route show two flags: expired, and expires within 30 days.

RealmSSO sends no alert and runs no scheduled check. A person must run the check or read the config. We have not measured whether the sign-in service picks up a rotated certificate from a metadata URL on its own.

Edit a connection

If the re-provision fails, the status becomes error, unless it was inactive. A failed re-provision, for example onto metadata with no signing certificate, leaves the existing identity provider and every user's link unchanged. See Connection status.

Delete a connection

Deleting a connection ends the sessions of every user who signed in through it. RealmSSO does this first. If it cannot end the sessions of one user, it logs a warning and goes on. Then it deletes the entry, and last the record. If RealmSSO cannot delete the entry, the delete fails and the record stays. A status change ends no session.

Test login URL

GET /api/v1/connections/:id/initiate is a stable URL for one connection. It needs no credential. It starts a login through that connection and lands the user on the account page of the realm. It does not land the user in your application. An IT admin can put it in the IdP's app tile as the sign-on URL. The config route returns it as idpInitiatedSignOnUrl.

The route answers 302 to the sign-in service. It answers 403 with the code CONNECTION_NOT_BROKERING when the connection does not accept new logins. It answers 404 when the connection or its entry does not exist.

Reference

All routes live under /api/v1/connections. A request with an X-API-Key header is an API key request. Any other request needs a dashboard session. See the API overview for credentials, roles and scopes. An API key must also belong to the account of the connection.

Create a SAML connection

Send a metadata URL, metadata XML or the three manual values. The response is 201. It holds the connection and its ssoConfig in data.

API=https://api.realmsso.com
curl -X POST "$API/api/v1/connections/saml" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"<account-id>","name":"Acme SAML","metadataUrl":"<idp-metadata-url>"}'

{
  "data": {
    "id": "<connection-id>",
    "accountId": "<account-id>",
    "type": "saml",
    "name": "Acme SAML",
    "status": "active",
    "keycloakIdpAlias": "saml-<connection-id>",
    "idpCertificateSet": true,
    "clientSecretSet": false,
    "ssoConfig": {
      "acsUrl": "<sign-in-origin>/realms/kr-<account-id>/broker/saml-<connection-id>/endpoint",
      "entityId": "<sign-in-origin>",
      "audience": "<sign-in-origin>"
    }
  }
}

Other fields are left out of this example.

Create an OIDC connection

The response is 201. The ssoConfig holds the redirect URI in redirectUris. The OIDC redirect URI is the sign-in service's own endpoint, not a RealmSSO route.

A connection response

A response also holds the other stored fields of the connection.

List connections

The accountId query parameter is required. Without it the route returns 400. The optional filters are type (saml or oidc) and status. The list is paginated with page and limit (maximum 100). Each result includes its ssoConfigs.

Get, update and delete a connection

PATCH takes a partial body. Every field is optional: name, status (active, inactive or error), the SAML and OIDC fields above, acsUrl and config. All of them accept null to clear the value, except name, status and config. RealmSSO encrypts a new clientSecret and never writes it to the audit log.

The PATCH response holds the connection in data and a brokering report. If RealmSSO cannot tell the sign-in service to stop new logins, the route answers 502. See Connection status.

DELETE answers 204. The response carries two headers, x-offline-access-outcome and x-offline-access-effective. They report what the delete did to the offline access of the account.

Check a connection

The route returns 400 when the connection has no entry yet. Otherwise it returns the result in data.

{
  "data": {
    "reachable": true,
    "latencyMs": 84,
    "certificateExpiresAt": "2027-03-01T00:00:00.000Z",
    "certificateExpired": false,
    "certificateExpiringSoon": false
  }
}

Read the display values

The route returns type, acsUrl, entityId, issuer and metadataUrl. For OIDC it also returns clientId, discoveryUrl and redirectUris. For SAML it also returns idpCertificateExpiresAt, idpCertificateExpired and idpCertificateExpiringSoon.

It returns idpInitiatedSignOnUrl, offlineAccess and the name and slug of the account. It never returns the client secret. The acsUrl and entityId fields hold only a value that you set yourself, at create time or with a PATCH. They are usually null. Use the routes in the section about the three values to read the real ones. The Admin Portal does not use this route.

Set the offline policy

Live now · API only. The body holds enabled (required), maxOfflineAgeSeconds (a positive integer, or null) and requiresDeviceLock. The value null means offline is not configured. It never means no limit. RealmSSO stores the policy. No device checks maxOfflineAgeSeconds or requiresDeviceLock today, because the device SDK is not released yet.

A window longer than the realm allows returns 400. enabled: true returns 400 while any connection of the account has the assertion grant on. The route also returns 400 when the account has neither an SSO client nor a mobile client yet. Offline continuity on a device: Building now. See Offline operation.

Assertion grant and agent principals

Three more routes live under /api/v1/connections. They belong to agent identity. See Agent Identity API.

Related routes

Errors