Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

OAuth2 / PKCE / BFF Pattern in Yunetas

Overview

Yunetas authenticates browser SPAs through a Backend-For-Frontend (BFF): the auth_bff yuno, which runs the C_AUTH_BFF gclass. The browser talks to the BFF only. The BFF is the only component that talks OAuth2 to the identity provider (IdP). The key security property: the tokens live in HttpOnly cookies, and JavaScript never reads them (the one opt-in exception is /auth/token).

The BFF gives the browser two ways in:

EndpointOAuth2 grantWho uses it
POST /auth/loginResource Owner Password Credentials (grant_type=password)The in-repo SPAs gui_agent and gui_treedb: their own login form posts {username, password}
POST /auth/callbackAuthorization Code + PKCE (grant_type=authorization_code)An SPA that sends the user to the IdP’s own login page. No in-repo SPA uses it today

After the login the two are the same: cookies, refresh, logout, and the cookie on the WebSocket upgrade.

The system is identity-provider agnostic. Keycloak is the IdP of every deployment so far, but the BFF code names everything as IdP (idp_calls, idp_timeouts, idp_timeout_ms). Any OIDC-compliant provider works. The full server-side contract is YUNO_AUTH.md §2.


Components Involved

LayerComponentFileRole
Frontend (JS)C_AGENT_LOGIN, C_TREEDB_LOGINyunos/js/gui_agent/src/c_agent_login.js, yunos/js/gui_treedb/src/c_login.jsPost the login form to the BFF, restore the session on load, arm the token refresh, log out
Config (JS)deploy_info()yunos/js/<spa>/src/conf/deploy.jsDerives the BFF URL from the serving host name (https://<host>:<bff port>). No per-host table
BFF Server (C)C_AUTH_BFF in the auth_bff yunokernel/c/root-linux/src/c_auth_bff.cHTTPS server on the port of its configuration. Exchanges credentials or codes for tokens, sets the cookies
WebSocket BridgeC_WEBSOCKETkernel/c/root-linux/src/c_websocket.cCaptures Cookie header from HTTP Upgrade request
GatekeeperC_IEVENT_SRVkernel/c/root-linux/src/c_ievent_srv.cExtracts access_token from the cookie (or the identity card’s jwt), injects it into the IDENTITY_CARD
Auth ManagerC_AUTHZkernel/c/root-linux/src/c_authz.cValidates JWT signature (JWKS), checks expiry/issuer/claims, manages roles
JWT Librarylibjwtkernel/c/libjwt/src/Cryptographic JWT verification (RS256, ES256, EdDSA and more.)

The BFF port is not fixed: it is the url of the auth_bff’s configuration (auth_bff.<port>.json). The in-repo SPAs expect it on their own host:

SPABFF
gui_agenthttps://<host>:1806 (agents plane), https://<host>:1807 (agent22 plane)
gui_treedbhttps://<host>:1808

On localhost the gui_treedb dev server proxies /auth/* to https://localhost:1808 (gui_treedb/vite.config.js), so the BFF base is same-origin there and the local BFF must listen on 1808. The localhost example of the yuno (yunos/c/auth_bff/batches/localhost/auth_bff.1801.json) listens on 1801. To use it with the dev server, set its __bff_secure_url__ to https://0.0.0.0:1808 before you load the batch:

"__bff_secure_url__": "https://0.0.0.0:1808"

Development behind a proxy

The vite proxy (changeOrigin: true) rewrites only the Host of the request. The Origin stays the one of the dev server (http://localhost:5173), and the BFF serves only the Origin of its SPA (see Logout Flow): a BFF with the production allowed_origin answers every login, refresh and logout from the dev server 403 origin_not_allowed, and its error names both origins:

{"success": false, "error_code": "origin_not_allowed",
 "error": "Origin 'http://localhost:5173' not allowed for /auth/logout: allowed_origin is 'https://app.example.com'"}

Do one of the two:

A logout refused this way leaves the session: the HttpOnly cookies stay, and a reload of the SPA restores it. So does a logout that does not reach the BFF. A logout the BFF serves clears the cookies whatever happens at the IdP (see Logout Flow).


The Three Key Concepts

1. BFF (Backend-For-Frontend)

The BFF is a thin server-side component that acts as a secure intermediary between the browser and the IdP. The browser never talks to the IdP’s token endpoint. The BFF:

2. The password grant (/auth/login)

The SPA shows its own login form and posts the username and password to the BFF, over HTTPS, and nowhere else. The BFF sends them to the IdP’s token endpoint with grant_type=password. The IdP client must allow it (“Direct Access Grants” in Keycloak), or every login is refused. The SPA never keeps the password, and never receives a token.

3. PKCE (Proof Key for Code Exchange) — RFC 7636

For the authorization-code flow (/auth/callback), PKCE prevents authorization code interception attacks. Before redirecting to the IdP, the browser:

  1. Generates a random code_verifier (32 bytes, base64url-encoded)

  2. Computes code_challenge = base64url(SHA-256(code_verifier))

  3. Sends the code_challenge to the IdP with the authorization request

  4. Later, the BFF sends the original code_verifier when exchanging the code

  5. The IdP verifies that SHA-256(code_verifier) == code_challenge

An attacker who intercepts the authorization code cannot use it because they do not have the code_verifier. The state and nonce are the SPA’s job: the BFF does not generate them.


Login Flow (/auth/login)

This is the flow of gui_agent and gui_treedb.

 ┌─────────────────────────────────────────────────────────────────────────┐
 │  STEP 1: The user submits the SPA's login form                         │
 │                                                                        │
 │  Browser (C_AGENT_LOGIN / C_TREEDB_LOGIN)                              │
 │  └── POST https://app.example.com:1808/auth/login                      │
 │      Content-Type: application/json                                    │
 │      credentials: "include"                                            │
 │      { "username": "john", "password": "..." }                         │
 └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
 ┌─────────────────────────────────────────────────────────────────────────┐
 │  STEP 2: The BFF asks the IdP for tokens (c_auth_bff.c)                │
 │                                                                        │
 │    POST https://auth.example.com/realms/{realm}/protocol/              │
 │         openid-connect/token                                           │
 │    Content-Type: application/x-www-form-urlencoded                     │
 │                                                                        │
 │    grant_type=password                                                 │
 │    &username=john                                                      │
 │    &password=...                                                       │
 │    &client_id={client_id}                                              │
 │    &client_secret=...  (only if the client is confidential)            │
 │                                                                        │
 │  The IdP responds with:                                                │
 │    { access_token, refresh_token, expires_in,                          │
 │      refresh_expires_in, token_type: "Bearer" }                        │
 │  Some IdPs add an id_token (it depends on the IdP and the scope);      │
 │  the BFF does not use it.                                              │
 └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
 ┌─────────────────────────────────────────────────────────────────────────┐
 │  STEP 3: The BFF sets HttpOnly cookies and responds                    │
 │                                                                        │
 │  ├── Reads username and email from the token claims                    │
 │  ├── Sets the cookies on the HTTP response:                            │
 │  │                                                                     │
 │  │   Set-Cookie: access_token=<JWT>; Max-Age=<expires_in>;             │
 │  │     Path=/; HttpOnly; Secure; SameSite=Strict[; Domain=<domain>]    │
 │  │   Set-Cookie: refresh_token=<JWT>; Max-Age=<refresh_expires_in>;    │
 │  │     Path=/; HttpOnly; Secure; SameSite=Strict[; Domain=<domain>]    │
 │  │                                                                     │
 │  └── Returns to the browser (NO tokens in the body):                   │
 │      {                                                                 │
 │        "success": true,                                                │
 │        "username": "john",                                             │
 │        "email": "john@example.com",                                    │
 │        "expires_in": 300,                                              │
 │        "refresh_expires_in": 1800                                      │
 │      }                                                                 │
 └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
 ┌─────────────────────────────────────────────────────────────────────────┐
 │  STEP 4: The browser opens the WebSocket (authenticated)               │
 │                                                                        │
 │  A cookie is not scoped by port, so the browser attaches it to the     │
 │  Upgrade request to any port of the same host:                         │
 │                                                                        │
 │  GET wss://app.example.com:1996/  HTTP/1.1                             │
 │  Upgrade: websocket                                                    │
 │  Cookie: access_token=<JWT>; refresh_token=<JWT>                       │
 └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
 ┌─────────────────────────────────────────────────────────────────────────┐
 │  STEP 5: Server-side JWT validation chain                              │
 │                                                                        │
 │  C_WEBSOCKET (c_websocket.c)                                           │
 │  └── Captures the Cookie header of the HTTP Upgrade request            │
 │      └── Passes it via EV_ON_OPEN { http_cookie: "..." }               │
 │                                                                        │
 │  C_IEVENT_SRV (c_ievent_srv.c) — the "gatekeeper"                      │
 │  └── Parses "access_token=<JWT>" from the cookie string                │
 │      └── Injects the JWT into the IDENTITY_CARD                        │
 │          └── Sends EV_IDENTITY_CARD to C_AUTHZ                         │
 │                                                                        │
 │  C_AUTHZ (c_authz.c) — authentication & authorization manager          │
 │  └── verify_token():                                                   │
 │      ├── Verify JWT signature using JWKS public keys (libjwt)          │
 │      ├── Check token expiry (exp claim)                                │
 │      ├── Validate issuer (iss claim)                                   │
 │      ├── Check email_verified claim                                    │
 │      ├── Look up user in treedb                                        │
 │      └── Assign roles and permissions                                  │
 │                                                                        │
 │  ✓ Connection authenticated → service GClasses can process events      │
 └─────────────────────────────────────────────────────────────────────────┘

A failed login answers with a stable error_code (for example invalid_credentials, account_disabled, auth_service_unavailable), which the SPA uses as its i18n key.


PKCE Authentication Flow

The BFF also serves the authorization-code flow, for an SPA that sends the user to the IdP’s own login page (or to a social login through it). Only the start differs from the flow above:

OIDC/PKCE auth sequence across Browser, auth_bff, Keycloak and the backend yuno — login phase (PKCE code exchange, HttpOnly cookie) and per-request phase (WS + cookie, JWKS verify, the per-command authz gate that runs only when enable_command_authz is set).

The PKCE login and the per-request phase.

  1. The SPA generates code_verifier, code_challenge (S256) and a state nonce, keeps the verifier and the state in sessionStorage, and redirects to the IdP:

    https://auth.example.com/realms/{realm}/protocol/openid-connect/auth
        ?response_type=code
        &client_id={client_id}
        &redirect_uri=https://app.example.com/
        &scope=openid profile email
        &code_challenge={challenge}
        &code_challenge_method=S256
        &state={state}
  2. The user authenticates at the IdP, which redirects back: 302 → https://app.example.com/?code=AUTH_CODE&state=STATE_NONCE.

  3. The SPA checks the state, removes ?code= from the address bar (history.replaceState()), and posts to the BFF:

    POST https://app.example.com:1808/auth/callback
    Content-Type: application/json
    credentials: "include"
    {
      "code": "AUTH_CODE",
      "code_verifier": "ORIGINAL_VERIFIER",
      "redirect_uri": "https://app.example.com/"
    }
  4. The BFF checks that allowed_redirect_uri allows the redirect_uri (see the table of the attributes), and calls the token endpoint with grant_type=authorization_code, the code and the code_verifier. The IdP checks SHA-256(code_verifier) == code_challenge.

  5. From here on it is step 3 of the login flow: cookies, and the same body.

With Keycloak, a social login (Google, GitHub and more) is the kc_idp_hint parameter of the authorization URL: Keycloak skips its own page and redirects to that provider. The BFF does not know which provider authenticated the user.


Session Restore and Token Refresh

On load, the SPA calls POST /auth/refresh. The tokens are HttpOnly, so the answer of the refresh is the only way a reloaded SPA learns that it has a session, and who it is (username, email).

The access token has a short lifetime (typically 5 minutes). The SPA arms the next refresh before it expires:

save_session_info()
├── timeout = max(0.75 * expires_in, expires_in - 30) seconds
│     (expires_in 300 → refresh after 270 s)
│
├── When the timer fires:
│     POST https://app.example.com:1808/auth/refresh
│     credentials: "include"  (sends the HttpOnly cookies)
│
├── C_AUTH_BFF:
│     ├── Reads refresh_token from the cookie
│     ├── Calls the token endpoint:
│     │     grant_type=refresh_token
│     │     &refresh_token=<from_cookie>
│     │     &client_id={client_id}
│     ├── Receives a new access_token + refresh_token
│     └── Sets new HttpOnly cookies (overwriting the old ones)
│
└── Browser receives { success, username, email, expires_in, refresh_expires_in }
    └── Arms the next refresh

The IdP can answer a refresh with no new refresh_token (RFC 6749 §6: the server MAY issue one, and when it does not, the client keeps the one it has). The BFF then sends no Set-Cookie for refresh_token: the browser keeps its cookie, and the next refresh uses it. Only the access_token cookie is replaced, and the answer carries no refresh_expires_in (no cookie was written for it to describe):

HTTP/1.1 200 OK
Set-Cookie: access_token=<new JWT>; Max-Age=300; Path=/; HttpOnly; Secure; SameSite=Strict
                                         ← no Set-Cookie: refresh_token=...

{"success": true, "username": "john", "email": "john@example.com", "expires_in": 300}

A login (or a callback) answered with no refresh_token opens a session that cannot be refreshed. There is no refresh_token to keep, so the BFF clears the cookie (Set-Cookie: refresh_token=; Max-Age=0; ...: no refresh_token of an earlier session stays in the browser), answers with no refresh_expires_in, and logs a WARNING once per process (“👤BFF IdP answered a login with no refresh_token: its session cannot be refreshed, it ends with its access_token (said once)”). The session ends when its access_token expires. The next refresh answers 401 missing_refresh_token. The logout of such a session works: see Logout Flow. To get refreshable sessions, configure the IdP client to issue refresh tokens.

A lifetime of 0 is a token with no expiry. Keycloak answers "refresh_expires_in": 0 for an offline token (scope offline_access). A Max-Age=0 tells the browser to delete the cookie on arrival, so the BFF writes that cookie with no Max-Age: a cookie of the browser session. A browser drops it when its session ends, but a browser that restores its session (Chrome and Firefox with “continue where you left off”) keeps it, so the cookie of an offline token can live as long as the token. The same holds for "expires_in": 0. The answer says the 0 as it came:

IdP:      {"access_token": "...", "expires_in": 300,
           "refresh_token": "...", "refresh_expires_in": 0}

BFF:      Set-Cookie: access_token=<JWT>; Max-Age=300; Path=/; HttpOnly; Secure; SameSite=Strict
          Set-Cookie: refresh_token=<JWT>; Path=/; HttpOnly; Secure; SameSite=Strict
          {"success": true, ..., "expires_in": 300, "refresh_expires_in": 0}

The SPAs read "expires_in": 0 as their default of 300 s for the next refresh (expires_in || 300).

The answer of the IdP is data of a peer, and the BFF reads it that way. A token that is not a string ("access_token": 123, "refresh_token": {}) is refused: 502 auth_unexpected_error, “Authentication service answered an access_token that is not a string”. Two WARNINGs with no stack say it: one names the token and its type (“👤BFF IdP answered a token that is not a string”, "type": "integer"), and one is the answer of the 502 (“👤BFF IdP answer refused”, "error_code": "auth_unexpected_error"). A success with no access_token is refused the same way, with that second WARNING only. A token goes into a Set-Cookie as it is, so a token with a byte that a cookie value cannot carry (outside RFC 6265 cookie-octet: a control byte, a space, ", ,, ;, \) is refused too, whole: 502 auth_unexpected_error (“Authentication service answered a refresh_token with a byte a cookie cannot carry”), with a WARNING that names the token, the position and the byte (“👤BFF IdP answered a token that is not a cookie value”), never the token. Without it, an access_token with ; Domain=evil.com adds an attribute, and a refresh_token with a CR LF begins another header. So is a success whose body is not a JSON object, answered 502 auth_empty_response: an empty body, text that is not JSON (a proxy’s HTML page), or another JSON type ([1, 2], the JSON string ""). Its error says which (“Authentication service answered success with an empty body”, “... with a body that is a JSON string, not an object”), and a body labelled application/json that does not parse also gets the WARNING of the HTTP parser (“data of a peer is not json”). The BFF reads at most 1 MB of the body of an IdP answer: a longer one is not read to the end (one WARNING of the HTTP client, “HTTP body larger than its limit, message refused”, and the connection to the IdP dropped), and the request is answered 502 auth_unexpected_error (“Authentication service answered a body longer than 1048576 bytes”). So is an answer whose headers pass the 64 KB the HTTP client takes (“... answered headers longer than 65536 bytes”), or that breaks the HTTP protocol once begun (“... answered an answer that breaks the HTTP protocol (...)”): the WARNING of the HTTP client, then the WARNING of the 502. Such an answer to a logout still clears the cookies, with a WARNING (“👤BFF IdP answer to a logout refused, the cookies are cleared”). Every other 5xx of the BFF is an ERROR (“👤BFF server error”). A lifetime (expires_in, refresh_expires_in) is a JSON integer or the text of one: "expires_in": "300" is read as 300, as some IdPs send it. Anything else ("expires_in": "soon", 300.5, false, a negative number) gets its default (300 for expires_in, 1800 for refresh_expires_in) and a WARNING that names the key and the value (“👤BFF IdP answered a lifetime that is not a number of seconds, its default is used”, "key": "expires_in", "value": "300.5").

A 429 of the IdP passes on its Retry-After (RFC 9110 §10.2.3). The BFF answers 429 auth_rate_limited with the Retry-After of the IdP when it is one of these, with the blanks around it removed:

The IdP sendsThe browser gets
delay-seconds of 1 to 10 digits: 120Retry-After: 120
IMF-fixdate: Wed, 21 Oct 2026 07:28:00 GMTRetry-After: Wed, 21 Oct 2026 07:28:00 GMT
RFC 850: Wednesday, 21-Oct-26 07:28:00 GMTRetry-After: Wed, 21 Oct 2026 07:28:00 GMT
asctime: Wed Oct 21 07:28:00 2026Retry-After: Wed, 21 Oct 2026 07:28:00 GMT

A date must be a real one: its day exists in its month, the time is 00:00:00 to 23:59:60, and the day-name is the one of that date. An RFC 850 year more than 50 years ahead is the same year a century before. The names are case-sensitive and the zone is GMT. Anything else is not passed on: 11 digits or more, Wed, 99 Oct 2026 ..., Thu, 21 Oct 2026 ... (a Wednesday), a list (120, 60), soon, -5. It gets a WARNING (“👤BFF IdP answered a Retry-After that is not delay-seconds (1 to 10 digits) nor an HTTP-date, not passed on”), so a value of the IdP never writes more than that one header. The CORS headers of every answer carry Access-Control-Expose-Headers: Retry-After, so a SPA on another origin than its BFF can read it, and waits what the IdP asks.

A request is sent to the IdP once. When the IdP closes the connection before it answers (it restarts, or the HTTP client cannot parse its answer), the BFF does not send the request again on the next connection: a second password grant, or a refresh_token used twice, which an IdP that rotates them takes for a stolen token. The browser gets 502 auth_service_unavailable (“Authentication service closed the connection before answering, the request is not sent again”), with the ERROR of the 502.

A refresh that cannot be made is not a logout. A network failure, a timeout (gui_treedb gives each BFF call 15 s) or a 5xx answer such as 502 auth_service_unavailable (the IdP is unreachable, for example on a node just after a reboot) says nothing about the user’s credentials. The SPA keeps the session and retries with backoff (5 s, doubling up to 60 s). A 4xx answer of the BFF (session_expired, missing_refresh_token) ends the session, except a 429, which is retried after its Retry-After. So does a code that a retry only gives again (token_too_large, auth_unexpected_error, auth_config_error, internal_error).


Logout Flow

POST https://app.example.com:1808/auth/logout
credentials: "include"
│
├── C_AUTH_BFF:
│   ├── Reads refresh_token from the cookie
│   ├── Calls the IdP end_session_endpoint to revoke it:
│   │     refresh_token=<from_cookie>
│   │     &client_id={client_id}
│   ├── Clears the cookies with Max-Age=0:
│   │     Set-Cookie: access_token=; Max-Age=0; HttpOnly; Secure; ...
│   │     Set-Cookie: refresh_token=; Max-Age=0; HttpOnly; Secure; ...
│   └── Returns { "success": true }
│
└── Browser: closes the WebSocket, shows the login screen

A logout ends in the browser whatever fails at the IdP. Every answer to a logout the BFF serves clears both cookies, its errors too, with no exception: the user is leaving, maybe on a shared machine, and the session must not stay in that browser. A logout is served when it carries a cookie and its Origin is the SPA’s. The two requests that are not served change nothing, because a cross-site request must not log a user out. The error tells the SPA that the session can still be open at the IdP (it ends there by its own timeout):

HTTP/1.1 502 Bad Gateway
Set-Cookie: access_token=; Max-Age=0; Path=/; HttpOnly; Secure; SameSite=Strict
Set-Cookie: refresh_token=; Max-Age=0; Path=/; HttpOnly; Secure; SameSite=Strict

{"success": false, "error_code": "auth_service_unavailable",
 "error": "Authentication service closed the connection before answering the logout, the cookies are cleared"}

The end-session is the one request that goes twice. Every other request to the IdP is sent once: a refresh_token used twice can end the session, a password grant must not be repeated by a client. Sending an end-session twice means the same as sending it once, and not sending it leaves the session open at the IdP. So when the IdP closes the connection before answering (the commonest cut is a connection kept open that it closed as the request left), the logout goes once more on the next connection, with a WARNING (“👤BFF IdP closed the connection before answering a logout, it is sent again”). A second cut is the 502 above.

A logout with no refresh_token cookie still ends the session in the browser. A session opened by a login answered with no refresh_token has no such cookie. The BFF then does not call the IdP (it has no refresh_token to end the IdP session with, and that session ends on the IdP by its own timeout), clears both cookies with Max-Age=0 at once, and answers 200 {"success": true}. It clears them only for a request that carries the access_token cookie: a cross-site form carries no cookie, and cannot log the user out.

Every request that reads or changes the session needs the Origin of the SPA: /auth/login, /auth/callback, /auth/refresh, a /auth/logout with a cookie (refresh_token or access_token) and /auth/token. SameSite=Strict says same SITE, not same origin: a sibling subdomain sends the cookies too, and a POST with no body (a refresh, a logout) needs no CORS preflight, so it reaches the BFF.

Another origin, no Origin, Origin: null, a sibling subdomain, the allowed origin with more after it (https://app.example.com.evil.com, https://app.example.com:8443) or a part of it, a Host that is a list (two Host lines, which RFC 9110 §7.2 makes invalid): 403 origin_not_allowed, no IdP call, no Set-Cookie. A browser sends Origin with every POST, same-origin included. A client that is not a browser must send it too. The error names the Origin received and the one allowed.

Request to /auth/logoutAnswer
refresh_token cookie, the SPA’s OriginIdP end-session call, both cookies cleared, 200 (also when the IdP answers an error. A 5xx, or an answer the HTTP client refuses, with a WARNING, “👤BFF IdP failed a logout, the cookies are cleared” for a 5xx)
The same, the IdP cuts the connection onceSent again on the next connection, both cookies cleared, 200
The same, the IdP cuts it twice, or the discovery failsBoth cookies cleared, 502 auth_service_unavailable
The same, the IdP stays silent or cannot be reachedBoth cookies cleared, 504 auth_timeout, within idp_logout_timeout_ms (10 s)
The same, the discovery has not ended within idp_logout_timeout_msBoth cookies cleared, 502 auth_service_unavailable
The same, the pending queue is fullBoth cookies cleared, 503 server_busy, no IdP call
The same, end_session_endpoint is not a URLBoth cookies cleared, 500 auth_config_error
refresh_token cookie longer than the BFF writes (name and value over 4096 bytes), the SPA’s OriginBoth cookies cleared, 400 token_too_large, no IdP call
access_token cookie only, the SPA’s OriginNo IdP call, both cookies cleared, 200
A cookie, the SPA’s Origin, a BFF with no IdP configured (no issuer, nor token_endpoint and end_session_endpoint)Both cookies cleared, 500 auth_config_error at once (a login, callback or refresh too, without cookies)
A cookie, another Origin or none403 origin_not_allowed, no IdP call, no Set-Cookie
No cookie (no session, or a cross-site request)200 {"success": true}, no Set-Cookie: nothing to end

The Exception: Backends on Other Hosts

A cookie does not travel to another host. gui_treedb opens treedb backends on hosts that the user configures, and the Monitor workspace of gui_agent talks to a node’s agent directly. For these, the SPA asks the BFF for the access token:

POST https://app.example.com:1808/auth/token
credentials: "include"
→ { "success": true, "access_token": "<JWT>" }

and puts it in the jwt of each C_IEVENT_CLI identity card. The remote C_IEVENT_SRV takes that jwt (there is no cookie), and C_AUTHZ validates it against the issuer’s JWKS like a cookie token: each remote backend needs the issuer’s JWKS in Authz.jwks and a role for the target service.

/auth/token is off by default and answers 404 unknown_endpoint. Turn it on only on the BFF of an SPA that needs it, with both settings:

"expose_access_token": true,
"allowed_origin":      "https://app.example.com"

The BFF gives the token only to a request whose Origin is exactly allowed_origin, else 403 origin_not_allowed. An XSS on that one origin can read the token, so keep the access-token lifetime short and the CSP of that SPA strict.


A Proxy on the Same Host as the Backend

A common deployment puts nginx on the host of the yunos, in front of the BFF (/auth/) and of the WebSocket of the backend (/ws):

location /ws {
    proxy_pass https://127.0.0.1:1840/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

This is a trap. The backend’s C_AUTHZ lets a peer of 127.0.0.* with no token log in as the local user yuneta, root, without a login: that is how the CLI of a node reaches its agent. Behind the proxy EVERY browser connects from 127.0.0.1. A client that sends an identity card with an empty jwt, no cookie, and the user yuneta is yuneta, with every command of the backend. The cookie and the Origin checks do not help: they are what the attacker leaves out.

The backend behind the proxy turns the login by address off, in its batch:

"global": {
    "Authz.trust_peer_ip": false
}

Then only a token (the BFF cookie, or the jwt of the card) or a password logs in, and a card with neither is refused: “Without JWT/passw the peer address is not trusted”. Keep it true (the default) on the agents. See trust_peer_ip in C_AUTHZ (new in 7.30.15). On an older SDK, make the proxy connect from an address out of 127.0.0.* (proxy_bind 127.0.1.1; in each location that proxies to the backend): a stopgap, which the next location added without it opens again.


Security Properties

PropertyHow it is achieved
JWTs never in JavaScriptTokens stored as HttpOnly cookies. document.cookie cannot read them. Exception: /auth/token, opt-in and origin-pinned
The password goes only to the BFF/auth/login over HTTPS. The SPA does not keep it, the BFF does not log it (traces redact it)
Code interception protection (/auth/callback)PKCE S256. Intercepted authorization codes are useless without code_verifier
CSRF protectionSameSite=Strict cookies, and the Origin of the SPA on every request that reads or changes the session (a sibling subdomain is same-site). For /auth/callback, the state nonce checked by the SPA
No open redirect of the codeallowed_redirect_uri: exactly it, or a path under it that no server reads out of it (no dot-segment, also before a ;, no \, no #, no %XX of a dot, a slash or a byte out of visible ASCII). Its host cannot be extended
A request is sent to the IdP onceNot sent again when the IdP closes the connection before it answers (502)
Token theft protectionSecure flag (HTTPS only). SameSite=Strict (no cross-site requests)
CORSThe BFF answers only allowed_origin. It never reflects an arbitrary Origin and never answers *
Server-side JWT validationC_AUTHZ verifies signature via JWKS, checks expiry, issuer, claims
Token refreshProactive refresh via the BFF before the access token expires
The form to the IdPEach key and value form-urlencoded (+, %, &, = of a password or a cookie are bytes of the value): a user cannot add parameters to a request the BFF signs with its client_secret
Pipelined requestsAnswered in their order (RFC 9112 §9.3.2): an answer the BFF knows at once waits behind a request still at the IdP

Each cookie set by the BFF carries these attributes:

Set-Cookie: access_token=<JWT>;
  Max-Age=<expires_in>; ← refresh_token: refresh_expires_in; none for a 0
  Path=/;               ← Sent with all requests to this host
  HttpOnly;             ← JavaScript cannot access (no document.cookie)
  Secure;               ← Only sent over HTTPS
  SameSite=Strict;      ← Never sent on cross-site requests (CSRF protection)
  Domain=<domain>       ← Only when cookie_domain is set and matches the Host

A cookie is not scoped by port (RFC 6265), so the cookie that the BFF sets (for example on port 1808) travels with the WebSocket Upgrade request to any other port of the same host, with or without Domain. The Domain attribute extends the cookie to the subdomains of cookie_domain. The BFF writes it only when cookie_domain is set and the request’s Host (without its port) is that domain or one of its subdomains. When the Host does not match, the BFF omits Domain, logs a WARNING (“cookie_domain does not match request Host, omitting Domain attribute”), and the cookie binds to the exact host of the request. A request with no Host gets no Domain either, with a WARNING (“request without Host, omitting Domain attribute”). So does a request whose Host name is longer than a host name can be (253 bytes), with a WARNING (“request Host longer than a host name, omitting Domain attribute”) whose host_len is the length of the name in the request ("host_len": 300 for a name of 300 bytes), measured before the BFF keeps 255 bytes of the Host.

A cookie with no Domain and a cookie with a Domain are two different cookies to a browser, also with the same name. The browser keeps both and sends both, the older first, and the BFF reads the first. So the BFF writes each cookie in one variant and expires the other variants that it can name: the cookie with no Domain, and Domain=<the host name of the request>. These Max-Age=0 lines come before the cookie that the BFF writes. Without them, a change of cookie_domain leaves the old cookie in each browser that has it. The BFF then reads a refresh_token of an ended session, and the session expires at its first refresh (invalid_grant, “Session not active”). A login on https://app.example.com, with an empty cookie_domain, answers:

Set-Cookie: access_token=; Max-Age=0; Path=/; HttpOnly; Secure; SameSite=Strict; Domain=app.example.com
Set-Cookie: refresh_token=; Max-Age=0; Path=/; HttpOnly; Secure; SameSite=Strict; Domain=app.example.com
Set-Cookie: access_token=<JWT>; Max-Age=300; Path=/; HttpOnly; Secure; SameSite=Strict
Set-Cookie: refresh_token=<JWT>; Max-Age=1800; Path=/; HttpOnly; Secure; SameSite=Strict

The BFF writes the host name into Domain only when it is a DNS name (letters, digits, . and -, at most 253 bytes). A request with no Host gets no such line. An answer that writes no cookie expires nothing: a refresh that keeps the browser’s refresh_token does not touch its variants either.

A token travels in a cookie and returns in one. A browser keeps a cookie only when its name and value take at most 4096 bytes (RFC 6265bis, in the algorithm that parses a Set-Cookie. Chrome and Firefox drop a bigger one with nothing said, and the session then opens with no token). RFC 6265 §6.1 is not that rule: it counts the name, the value and the attributes, and it is a minimum a browser must keep. So the BFF takes an access_token of at most 4084 bytes (4096 less access_token) and a refresh_token of at most 4083 (4096 less refresh_token). A bigger token is refused by its size, before anything reads it: 500 token_too_large, and its error says the sizes (“Token too large for a browser cookie: access_token 5120 bytes (limit 4084), refresh_token 652 bytes (limit 4083); a cookie name and value take at most 4096 bytes”). An IdP that answers a success with no access_token is refused too: 502 auth_unexpected_error, “Authentication service answered success with no access_token”.

The same rule reads the cookies that return. A refresh_token cookie (/auth/refresh, /auth/logout) of more than 4083 bytes, or an access_token cookie (/auth/token) of more than 4084 (name and value over 4096 bytes), is none the BFF wrote: 400 token_too_large, “refresh_token cookie of 4084 bytes: the BFF writes none longer than 4083 (a cookie name and value take at most 4096 bytes)”, and it goes nowhere. At /auth/logout that answer clears both cookies, as every answer to a logout served. A cookie that fits is taken whole.


Configuration

BFF Server (C_AUTH_BFF attributes)

{
  "issuer":               "https://auth.example.com/realms/myrealm/",
  "client_id":            "app.example.com",
  "client_secret":        "",
  "cookie_domain":        "app.example.com",
  "allowed_origin":       "https://app.example.com",
  "allowed_redirect_uri": "https://app.example.com/",
  "expose_access_token":  false,
  "crypto":               {"ssl_use_system_ca": true, "ssl_verify_mode": "required"},
  "pending_queue_size":   16,
  "idp_timeout_ms":       30000,
  "idp_connect_timeout_ms": 30000,
  "idp_logout_timeout_ms": 10000
}
AttrDefaultPurpose
issuer— (required, or issuers)OIDC issuer URL (for example https://auth.example.com/realms/foo/). Triggers discovery via /.well-known/openid-configuration. Use token_endpoint + end_session_endpoint instead to bypass discovery.
issuers[]Two or more issuer URLs of the same realm, one on each IdP, in order of preference: "issuers": ["https://auth.example.com/realms/foo/", "https://auth2.example.com/realms/foo/"]. Replaces issuer. A login goes to the first IdP that answers. A refresh or a logout goes to the IdP of its session. See Failover between IdPs.
idp_failover_connect_ms4000With issuers: the time a login waits for an IdP to connect before it goes to the next IdP.
idp_failover_response_ms5000With issuers: the time a login waits for the answer of an IdP before it goes to the next IdP, when the next IdP is up. Example: "idp_failover_response_ms": 5000.
idp_down_retry_ms60000With issuers: the time the logins skip an IdP that failed a login.
client_id, client_secret—OAuth2 client credentials (leave client_secret empty for a public client).
cookie_domain""Domain= attribute on the cookies. Written only when the request Host is this domain or a subdomain of it. Otherwise omitted, with a WARNING. Empty: never written (host-only cookies).
allowed_origin""The origin of the SPA: the CORS origin, the one Origin served for login, callback, refresh, logout and token (else 403), and the origin /auth/token is pinned to. It is what pins the scheme. Empty: no cross-origin access, the Origin must be the BFF’s own (https:// and the Host, or http:// and it on a connection that is not TLS), and /auth/token is refused.
allowed_redirect_uri""The redirect_uri a /auth/callback can have. Without a / at its end, exactly it: "https://app.example.com/auth/callback". Ending with / after a scheme and a host, one that starts with it and whose rest is a path and query in it: "https://app.example.com/app/" allows https://app.example.com/app/cb?x=1, .../app/a%41;v=1 and any query, not https://app.example.com/app/../admin, .../app/%2e%2e/x, .../app/..\x, .../app/x#f, a space or a byte over 0x7E. A prefix is a strict rule: what RFC 3986 allows and some server normalizes out of the prefix is refused too, so an empty segment but the last (under "https://app.example.com/", https://app.example.com//evil.com/, whose path is a URL with no scheme to whoever repeats it in a relative Location, and .../app/x/ passes), a . or .. segment before a ; (.../app/..;/x, which Tomcat reads as ..), and in the path a %XX of ., /, \, ;, ?, #, % or a byte out of visible ASCII (.../app/..%2Fx, .../app/%5c..%5cx, .../app/%252e%252e/x, .../app/%c0%ae/x), or one badly written (.../app/x%zz). Its host cannot be extended: https://app.example.com.evil.com/ and https://app.example.com@evil/ never pass "https://app.example.com/". Empty: not checked, so set it whenever the BFF serves /auth/callback.
expose_access_tokenfalseEnables /auth/token. Needs allowed_origin.
crypto{"ssl_use_system_ca": true, "ssl_verify_mode": "required"}TLS crypto for the outbound IdP HTTP client. Verifying-by-default since 7.6.0: a public IdP is validated against the system CA store by default. For a private/self-signed IdP CA, override with {"ssl_trusted_certificate": "/path/ca.pem"}. The attribute replaces the default wholesale (no merge), so an override must repeat the verifying keys it still wants. mbedTLS has no system store: set ssl_trusted_certificate there. (The c_idp_keycloak kc_crypto attribute mirrors this for its Keycloak admin calls.)
pending_queue_size16 (clamped to [1, 1024])Depth of the per-channel pending IdP request queue. Raised on front-line BFFs under burst.
idp_timeout_ms30000 (0 or less: the default, 30000)Bounds the IdP round-trip once connected. On expiry the browser gets 504. It cannot be turned off: a round-trip is always bounded, "idp_timeout_ms": 0 is 30000.
idp_connect_timeout_ms30000 (0 disables)Bounds the wait to connect to the IdP. See YUNO_AUTH.md §2.6.
idp_logout_timeout_ms10000 (0: only the two above bound a logout)Bounds the whole of a logout: the wait for the discovery and the connection, the end-session and its resend. When it passes the logout is answered with both cookies cleared. Keep it under the time the SPA waits (15 s), or the answer comes to nobody and the cookies stay. Accuracy of a second (C_TIMER).

Failover between IdPs

When the realm is served by two IdPs (one imported from the other, with its keys), set issuers instead of issuer. Every C_AUTHZ of the backend yunos must accept both issuers. The BFF cannot move a session from one IdP to the other: a refresh token presented to the other IdP is refused with invalid_grant, “Invalid token issuer”. So:

An IdP that failed a login is skipped by the logins for idp_down_retry_ms. The first login after that time tries it again. The BFF logs the change of state once (WARNING down, INFO up). The idp_failovers stat counts the logins that went to the next IdP.

BFF internals (operator knobs)

A few details that are not visible in the request/response flow but matter in production:

Frontend (conf/deploy.js)

The SPA has no table of hosts: one build serves every deployment, and the BFF URL is derived from the host that serves the SPA.

This is gui_treedb/src/conf/deploy.js:

const BFF_PORT = 1808;   /* auth_bff for the treedb GUI plane */

function deploy_info()
{
    let host = (typeof window !== "undefined" && window.location && window.location.hostname)
        ? window.location.hostname : "localhost";

    let tenant = (host.split(".")[0]) || "local";
    let is_local = (host === "localhost" || host === "127.0.0.1");

    return {
        host:    host,
        tenant:  tenant,
        bff_url: is_local ? "" : `https://${host}:${BFF_PORT}`
    };
}

IdP Client Settings (Keycloak)

One client per BFF, in the realm of the project.

SettingValue
Direct Access GrantsOn: /auth/login uses grant_type=password. Without it every login is refused
Standard FlowOn only if the BFF must also serve /auth/callback
Client AuthenticationOff (public), or On (confidential) with client_secret in the BFF config
PKCE MethodS256 (only for /auth/callback)
Valid Redirect URIshttps://app.example.com/* (only for /auth/callback)
Web Originshttps://app.example.com

Why BFF Instead of Direct Token Exchange?

Without a BFF, the browser calls the IdP’s token endpoint directly and receives the JWT in a JavaScript-accessible response. This exposes tokens to:

With the BFF pattern, the token exchange happens server-to-server. The browser only receives metadata (username, expires_in). The actual JWT travels only in HttpOnly cookies that JavaScript cannot read, and the browser attaches them to the later requests by itself.