How to configure Single Sign-On (SSO) with header-based authentication

This guide explains how to enable Single Sign-On (SSO) for Yurbi using header-based authentication. With this method, an identity provider (such as Microsoft Entra ID) authenticates your users, passes their identity to Yurbi in a trusted request header, and Yurbi logs them in automatically — no separate Yurbi login required.

1. Overview

Yurbi supports a header-based SSO model. The flow works like this:

Your identity provider (or the proxy in front of it) authenticates the user.
It sends a request to Yurbi's dedicated SSO endpoint with the user's login ID in a trusted HTTP header.
Yurbi reads the header, validates the user, generates a session token, and redirects the user straight into the application.

The user clicks your Yurbi link (for example, a tile in their Microsoft portal) and lands inside Yurbi already signed in.

A few important points before you begin:

Existing users only. Header-based SSO signs in users who already exist in Yurbi. It does not create new accounts. The value passed in the header must match an existing Yurbi user's login ID.
Any authentication type. The user can be a standard (password) Yurbi user. They do not need to be configured for Windows authentication.
The endpoint must be protected. Because Yurbi trusts the identity in the header, the SSO endpoint must be reachable only through your trusted identity proxy. See Section 4: Securing the SSO endpoint — this step is required, not optional.

2. Enabling SSO in Yurbi

SSO is configured entirely in the Yurbi admin interface — no manual file edits are required.

Go to Settings → Server Settings → Security Settings.
Under SSO Settings, turn on Enable SSO.
In the SSO Header field, enter the header name Yurbi should look for. This is the name of the HTTP header your proxy will send. Choose a non-obvious value, for example ssoheadertoken.
Save your changes.

That's the entire Yurbi-side setup.

Note on the SSO Header name: The header name identifies which header carries the user's identity. The header value is the user's Yurbi login ID. For example, if your SSO Header is set to ssoheadertoken, your proxy sends:
ssoheadertoken: jsmith
where jsmith is the login ID of an existing Yurbi user.

Leave Enable IIS Passthrough turned off for header-based SSO. (IIS Passthrough is a separate, Windows-only method and cannot be used at the same time as SSO.)

3. How the login request works

Once SSO is enabled, your proxy sends an authenticated request to the Yurbi SSO endpoint with the identity header attached.

The endpoint differs by platform:

Linux: https://{your-yurbi-server}/sso
Windows: https://{your-yurbi-server}/yurbi/sso

Yurbi validates the header, creates a session, and redirects the user into the app. By default the user lands on the Dashboard. You can send them to a different starting view by adding the h parameter that Yurbi already supports for seamless login:

Destination	URL the proxy targets (Linux example)
Dashboard (default)	`https://{your-yurbi-server}/sso`
Library	`https://{your-yurbi-server}/sso?h=1`
Builder	`https://{your-yurbi-server}/sso?h=2`

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

4. Securing the SSO endpoint

This section is essential. Do not enable SSO in production without completing it.

Because the SSO endpoint trusts whatever login ID arrives in the header, anyone who can reach that endpoint directly — and who knows the header name and a valid login ID — could sign in as that user. The header name is not a secret on its own, and login IDs are often easy to guess (for example, an email address).

The real protection is making sure the SSO endpoint can only be reached by your trusted identity proxy, never directly from the internet. There are three common ways to enforce this. Which one you use depends on your environment and what your proxy can send.

a) Shared secret (recommended — simplest)

Your proxy attaches an additional secret header (a long, random value) to every request it forwards to Yurbi. The proxy in front of Yurbi rejects any request that doesn't carry the matching secret. Because an outside attacker doesn't know the secret, they can't forge a direct request.

This is the easiest to set up and the most portable across environments. It does require that your identity proxy can inject a fixed, constant header value.

b) IP allowlist

The proxy in front of Yurbi only accepts SSO requests from your identity proxy's IP address and rejects all others. Simple to configure, but you'll need to update it if your proxy's outbound IP changes.

c) Mutual TLS (mTLS)

Your identity proxy presents a client certificate that the Yurbi-side proxy verifies before allowing the request. This is the strongest option but requires the most setup on both ends, and your identity proxy must support presenting a client certificate.

5. Implementation notes by platform

The way you enforce Section 4 depends on what sits in front of Yurbi. Yurbi itself doesn't manage your web server or TLS, but the guidance below is a starting point for the most common setups.

Linux (NGINX)

On Linux, Yurbi typically runs behind NGINX, and we'll assume SSL is terminated on the Yurbi server's NGINX. The principle is: create a dedicated location for /sso that enforces your chosen protection, and make sure the Yurbi application itself is not reachable except through NGINX.

A shared-secret example — only requests carrying the correct secret header are allowed to reach the SSO endpoint:

# Dedicated rule for the SSO endpoint
location = /sso {
    # Reject anything that doesn't present the shared secret
    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;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

An IP-allowlist variation:

location = /sso {
    allow 203.0.113.10;   # your identity proxy's address
    deny all;
    proxy_pass http://127.0.0.1:5000;
    proxy_set_header Host $host;
}

Two things to confirm regardless of method:

Require HTTPS. SSO requires SSL/TLS. If your Yurbi server isn't already serving HTTPS, that must be set up first (for example with a certificate on NGINX). The header carries a user's identity, so it must never travel over plain HTTP.
Don't allow bypass. Bind the Yurbi application to localhost (or an internal interface) so requests can't reach it except through NGINX. Otherwise the /sso rule can be circumvented.

Windows (IIS)

On Windows, Yurbi runs under IIS at /yurbi/sso, so NGINX rules don't apply — you enforce the same protection using IIS features:

Shared secret: Use an IIS request-filtering / URL Rewrite inbound rule on the /yurbi/sso path that checks for the secret header (for example HTTP_X_SSO_SECRET) and blocks the request if it's missing or doesn't match.
IP allowlist: Use the IP Address and Domain Restrictions feature in IIS, scoped to the /yurbi/sso path, to allow only your identity proxy's address.
Mutual TLS: Configure client certificate negotiation/requirement on the site (or the /yurbi/sso path) so only a request presenting your issued client certificate is accepted.

As with Linux, ensure the site is served over HTTPS and that the SSO path can only be reached through your protected front door.

Whichever platform and method you choose, the goal is the same: only your trusted identity proxy can reach the SSO endpoint. Yurbi confirms the user exists; your proxy is what proves the request is legitimate.

6. Supported identity providers

Header-based SSO is a long-established, vendor-neutral pattern, so Yurbi works with any system that can authenticate a user and forward their login ID in an HTTP header. Below are the common categories.

Microsoft Entra ID (most common)

Microsoft Entra application proxy (formerly Azure AD Application Proxy) is the most popular choice and supports header-based SSO natively. Microsoft Entra application proxy natively supports single sign-on to applications that use headers for authentication, where you configure the header values in Microsoft Entra ID and they're sent to the application via the proxy. The header values are drawn from standard Entra ID claims, so you can map a user's identity (such as their username or email) directly into the header Yurbi expects.

To use this with Yurbi, you publish Yurbi as an on-premises application through Entra application proxy, choose header-based single sign-on, and map the appropriate user attribute to your configured SSO Header name. (Note that Entra application proxy's connector runs on a Windows Server in your network, even if your Yurbi server runs on Linux.)

Modern identity-aware proxies

A growing category of "identity-aware proxy" / "SSO proxy" tools authenticate users against a modern identity provider (OIDC, SAML) and then inject identity headers into the request to your application. These are the modern successors to the legacy products below, and are a good fit if you don't already use Entra application proxy. Common options include:

oauth2-proxy
Authelia
Authentik
Pangolin
Forward-auth middleware in NGINX, Traefik, or Envoy

Any of these can sit in front of Yurbi, perform the login against your identity provider, and forward the user's login ID in your configured SSO Header.

Legacy / enterprise access managers

Many enterprises already run a web access management product that performs exactly this kind of header injection. If you have one of these in place, you can typically point it at Yurbi's SSO endpoint:

CA / Broadcom SiteMinder (formerly CA SiteMinder)
Oracle Access Manager (OAM)
IBM Security Verify Access (formerly Tivoli Access Manager / ISAM)
F5 BIG-IP Access Policy Manager (APM)
Ping Identity (PingAccess)
NetIQ / Micro Focus Access Manager
HP IceWall

7. Summary

Enable SSO in Settings → Server Settings → Security Settings, and set your SSO Header name.
Configure your identity provider / proxy to authenticate the user and send their Yurbi login ID in that header to the SSO endpoint (/sso on Linux, /yurbi/sso on Windows).
Secure the SSO endpoint so only your trusted proxy can reach it (shared secret, IP allowlist, or mutual TLS), and ensure it's served over HTTPS.
Users are signed in automatically and dropped into the Dashboard, Library, or Builder as configured.

If you'd like help mapping your specific identity provider to Yurbi, reach out to the Yurbi team and we'll walk through your setup.