Get API access
Guides

Header-based SSO (advanced)

A special case: let an identity provider like Microsoft Entra ID authenticate users and log them into Yurbi automatically via a trusted request header.

Most integrations don't need this. If your application can call DoLogin, use Single Sign-On — that's the standard answer, and it's simpler. Header-based SSO is for the specific case where you want your identity provider (e.g. Microsoft Entra ID) to authenticate the user and have Yurbi log them in automatically from a trusted header, with no DoLogin call from your side.

With header-based SSO, your identity provider authenticates the user, passes their Yurbi login ID to Yurbi in a trusted HTTP header, and Yurbi signs them in.

Before you start:

  • Existing users only. SSO signs in users who already exist in Yurbi; it does not create accounts. The header value must match an existing user's login ID.
  • Any auth type. The user can be a standard password user.
  • The endpoint must be protected. Because Yurbi trusts the header, the SSO endpoint must be reachable only through your trusted proxy (see Securing the endpoint).

1. Enable SSO in Yurbi

  1. Go to Settings → Server Settings → Security Settings.
  2. Under SSO Settings, turn on Enable SSO.
  3. In SSO Header, enter the header name your proxy will send (choose a non-obvious value, e.g. ssoheadertoken).
  4. Save.

The header name identifies which header carries the identity; the header value is the user's login ID. So your proxy sends, for an existing user jsmith:

ssoheadertoken: jsmith

Leave Enable IIS Passthrough off for header-based SSO.

2. The SSO endpoint

Once enabled, your proxy sends an authenticated request to Yurbi's SSO endpoint with the identity header attached. The path differs by platform:

Linux:    https://your-yurbi-server.com/sso
Windows:  https://your-yurbi-server.com/yurbi/sso

(On a Windows install with the IIS root web configured, the SSO endpoint is reachable at /sso even though the API stays at /yurbi/api.)

By default the user lands on the Dashboard. Add h to choose a starting view:

Dashboard (default):  /sso
Library:              /sso?h=1
Builder:              /sso?h=2

(On Windows use /yurbi/sso in place of /sso.)

3. Securing the endpoint (required)

Because the endpoint trusts the login ID in the header, it must only be reachable by your trusted proxy — never directly from the internet. Choose one:

  • Shared secret (recommended). Your proxy attaches an extra secret header with a long random value; the proxy in front of Yurbi rejects any request without it.
  • IP allowlist. Accept SSO requests only from your identity proxy's IP.
  • Mutual TLS (mTLS). Your proxy presents a client certificate Yurbi's front-end verifies. Strongest, most setup.

Always serve the endpoint over HTTPS, and bind the Yurbi app so it can't be reached except through your proxy.

NGINX (Linux) — shared-secret example

location = /sso {
    if ($http_x_sso_secret != "REPLACE_WITH_LONG_RANDOM_SECRET") { return 403; }
    proxy_pass http://127.0.0.1:5000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

IIS (Windows)

Use a request-filtering / URL Rewrite rule on /yurbi/sso to require the secret header, or IP Address and Domain Restrictions scoped to that path, or client-certificate negotiation for mTLS.

4. Supported identity providers

Header-based SSO is vendor-neutral — any system that can authenticate a user and forward their login ID in a header works. Common choices:

  • Microsoft Entra application proxy (most common) — supports header-based SSO natively; map a user attribute to your SSO Header name.
  • Identity-aware proxies — oauth2-proxy, Authelia, Authentik, or forward-auth in NGINX / Traefik / Envoy.
  • Enterprise access managers — SiteMinder, Oracle Access Manager, IBM Security Verify Access, F5 BIG-IP APM, PingAccess.

Need help mapping your specific provider? Reach out to the Yurbi team.