Enterprise SSO — SAML 2.0

BharatRouter is a SAML Service Provider (SP): your organisation's identity provider (IdP) authenticates your people, and BharatRouter accepts the signed assertion to sign them in. It is built into the gateway — assertions are validated in-India, with no third-party SSO broker in the identity path. This is an Enterprise feature.

How it works

1. A user visits /auth/saml/<connection>/login → BharatRouter redirects them to your IdP with a signed AuthnRequest.
2. Your IdP authenticates them and POSTs a signed assertion back to the ACS URL.
3. BharatRouter validates the signature, audience and expiry, checks the asserted email is on a verified domain of your org, then issues the same session a normal sign-in would.

One connection per organisation. The asserted email must belong to a domain you have verified under Teams & workspaces — an IdP can only sign in identities on a domain your org has proven it controls.

Prerequisites

• You are the org owner (only the owner can configure SSO).
• At least one verified company domain (DNS-TXT verified).
• Your IdP's entityID, SSO URL and signing certificate (PEM).

Set it up

Save the connection (draft, enabled:false) to get your SP values, hand them to your IdP, then flip enabled:true.

curl -X PUT https://api.bharatrouter.com/me/sso \
  -H "Content-Type: application/json" --cookie "br_session=..." \
  -d '{
    "idp_entity_id": "https://idp.example.com/metadata",
    "idp_sso_url":   "https://idp.example.com/sso/saml",
    "idp_cert":      "-----BEGIN CERTIFICATE-----\nMII...\n-----END CERTIFICATE-----",
    "default_role":  "member",
    "jit_provision": true,
    "require_sso":   false,
    "enabled":       false
  }'

The response returns your SP details to register at the IdP:

{
  "ok": true,
  "sp": {
    "entity_id":    "https://api.bharatrouter.com/auth/saml/sso_…/metadata",
    "acs_url":      "https://api.bharatrouter.com/auth/saml/sso_…/acs",
    "metadata_url": "https://api.bharatrouter.com/auth/saml/sso_…/metadata"
  }
}

SP metadata XML is served at the metadata_url for IdPs that import it directly. Once your IdP is configured, PUT again with "enabled": true.

Options

• default_role — the role granted to provisioned users: member(default) or admin. SSO never grants owner.
• jit_provision — when true (default), a first-time user on a verified domain is created and added to the org on their first SAML login. Whenfalse, only users who are already members can sign in.
• require_sso — when true, an OAuth (Google/GitHub) sign-in that resolves to this org is bounced to SAML instead. This gates actingin the org; a user's personal context is unaffected.

Security model

• Signed assertions required. The assertion's XML signature is validated against your pasted certificate; audience and expiry are enforced.
• Domain-bound. An assertion is honoured only if the email's domain is a verified domain of the org — an IdP can't mint identities on domains it doesn't own.
• Sovereign. Validation happens in the BharatRouter gateway in India; no external SSO broker ever sees your assertions or employee emails.
• Auditable. sso.login.success, sso.login.rejectedand sso.config.update are written to the org audit log.

Remove SSO

curl -X DELETE https://api.bharatrouter.com/me/sso --cookie "br_session=..."

SCIM provisioning (automatic add/deactivate from your directory) is on the roadmap and will attach to the same connection.