Exempt /zosmf/services/authenticate from the auth gate (AUTH=NONE) so mvsMF owns the login/logout response

[mgrossmann]

Summary

The deployed httpd gates /zosmf/services/authenticate under the /zosmf/*
AUTH=BASIC route policy, so auth_gate() rejects an unauthenticated
request to the authenticate endpoint with httpd's own 401 before dispatching
to the mvsMF CGI. Per the Auth redesign (docs/auth-redesign.md §2.5, #98) the
authenticate route was meant to "resolve but not reject" — i.e. resolve any
credential but always pass through, so mvsMF owns the login/logout response.

This is a design/config gap, not a functional blocker (see Impact) — filing
it so the httpd team can decide whether to close the gap or accept the current
behavior.

Behavior today (live, mvsdev.lan:1081)

A bad-credential POST /zosmf/services/authenticate gets httpd's generic 401,
never reaching mvsMF:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="MVS"
Server: HTTPD Server            <- httpd's auth_gate, not the CGI
Content-Type: text/plain
401 Unauthorized

mvsMF's handler would instead return the z/OSMF-shaped body:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{"returnCode":8,"reasonCode":1,"message":"Login failed. ..."}

Same for DELETE without a token (httpd 401 before the CGI).

Impact — mostly cosmetic

• Valid login is unaffected: the resolver sets httpc->cred from valid
  Basic, the gate passes, mvsMF returns 200 + LtpaToken2. ✔
• Bad login still returns 401 (correct status); only the body differs
  (httpd text/plain vs. mvsMF's z/OSMF JSON). Zowe/z/OSMF clients act on the
  status code, not the body — so no functional breakage.
• Logout without a valid token → 401 is actually correct per the z/OSMF
  spec ("request cookie must include a valid token").

What is lost by gating the route:

1. mvsMF cannot emit the exact z/OSMF wire format (returnCode/reasonCode/
   message) on the login-failure path.
2. The login endpoint answers with WWW-Authenticate: Basic realm="MVS" —
   real z/OSMF's /zosmf/services/authenticate does not send a challenge on
   this endpoint (it hands back a JSON result), and a Basic challenge can trigger
   a browser-native credential dialog for some client types.

Suggested fix

Give /zosmf/services/authenticate a more-specific route with AUTH=NONE
(overriding the broader /zosmf/* AUTH=BASIC). resolve_credential() runs for
every request before auth_gate(), so a valid Basic/token still populates
httpc->cred; AUTH=NONE just stops the gate from rejecting, letting every
request reach mvsMF, which then owns the response (200 + token on success, the
z/OSMF 401 on failure, 204/handled logout). This mirrors how httpd's own
/login and /logout are dispatched before the gate (see the
is_asset_exempt() note in src/httppc.c).

Decision for the team

Is exact z/OSMF wire fidelity (and no Basic challenge) on the authenticate
endpoint worth the extra route, or is httpd's front-gate 401 acceptable? If the
latter, this is wontfix and mvsMF's failure-path handler is effectively dead
code (harmless) — we'd relax the mvsMF tests accordingly.

References

• src/httppc.c: auth_gate() (~L346), auth_required_response() (~L396),
  resolve_credential() (~L268), is_asset_exempt() (~L326)
• docs/auth-redesign.md §2.5 · per-route policy Auth 3/6 (httpd): per-route auth policy in MOD= + challenge decoupling #98 · Epic Epic: Auth redesign (Form + Basic + z/OSMF token, per-route policy, HTTPX export) #100
• Consumer: mvsMF: implement /zosmf/services/authenticate (Authentication Service) mvsmf#162 / PR #168

[mgrossmann]

Analysis + assessment (httpd side)

Verified the claims against src/httppc.c — all accurate:

• resolve_credential() runs before auth_gate() for every method (httppc.c:62, shared switch body), so a valid Basic/token still populates httpc->cred regardless of the gate.
• /zosmf/* AUTH=BASIC → auth_gate() rejects an unauthenticated request with httpd's 401 + WWW-Authenticate: Basic realm="MVS" before the CGI (auth_required_response()).
• AUTH=NONE → need_authn=0, Stage-2/RES skipped → request reaches the CGI, which owns the response.

The fix is zero-code — the #98 per-route machinery already supports it. It's a single Parmlib route line.

Important mechanics caveat (the issue understates this)

http_find_cgi() (httpfcgi.c) is first-match in Parmlib order, not longest-prefix/most-specific. "A more-specific route overriding the broader /zosmf/*" only works if the AUTH=NONE route is listed before /zosmf/*:

MOD=MVSMF /zosmf/services/authenticate  AUTH=NONE
MOD=MVSMF /zosmf/*                       AUTH=BASIC

samplib/httpprm0 already documents this ordering rule for LOC= ("list specific prefixes before a catch-all"), so it's consistent — but it's a silent footgun if ordered wrong.

Security is unchanged

• Only the exact /zosmf/services/authenticate becomes AUTH=NONE; the rest of /zosmf/* stays BASIC.
• resolve_credential() (incl. cred_login/racf_login) already runs on every request before the gate, so the gate is response-shaping, not brute-force protection — relaxing it does not enlarge the credential-guessing surface (CRED_MAX flood cap stays in cred_login).
• Valid login → cred set → mvsMF 200 + LtpaToken2; bad login → cred==NULL → mvsMF returns the z/OSMF 401 JSON; logout without token → mvsMF 401. All correct, provided mvsMF gates its handler on httpc->cred==NULL (Add /zosmf/services/authenticate token login/logout mvsmf#168).

Recommendation

Do it — as a config + doc change, not code:

1. Add the AUTH=NONE authenticate route before /zosmf/* in the deployed HTTPPRM member and as a documented example in samplib/httpprm0.
2. Keep httpd generic — do not hardcode /zosmf/services/authenticate into httpd like /login//logout; the config route is the right layer.
3. Do not bundle a matcher rewrite (first-match → longest-prefix) into this — separate, broader decision; not needed here.

Cost of not doing it is cosmetic (clients act on status, already correct); mvsMF's failure-path handler is then harmless dead code → a clean wontfix is also defensible. Priority:low fits.

Edge notes: trailing-slash variants (…/authenticate/) fall through to /zosmf/* BASIC (z/OSMF uses the exact path, so fine); AUTH=NONE+RES= is already rejected by the parser (httpprm.c:441).

[mgrossmann]

Confirmed live — the config change works end-to-end

Thanks for the thorough analysis — agree with all of it. The AUTH=NONE
authenticate route is now deployed and verified against mvsdev.lan:1081
(mvsMF build f217b97). The route reaches the CGI, and mvsMF owns the full
response:

• valid login → 200 + LtpaToken2
• bad login → mvsMF's z/OSMF 401 {"returnCode":8,"reasonCode":1,…} (was
  httpd's generic text/plain 401 before)
• logout without a token → mvsMF 401 (z/OSMF requires a valid token)
• logout with a token → 204 + token invalidation

Agree with the three recommendations — config + doc, keep httpd generic (no
hardcoded path), and no matcher rewrite bundled in. The first-match ordering is
the key gotcha; the deployed member forwards the route correctly (bad login
reaches mvsMF), consistent with listing the AUTH=NONE line before
/zosmf/*.

Re your note "provided mvsMF gates its handler on httpc->cred==NULL" —
confirmed in mvslovers/mvsmf#168: the login handler treats a NULL credential
(http_get_token() == 0) as a failed login and returns the z/OSMF 401; the
logout handler returns 401 when http_logout() reports no credential. mvsMF's
curl-auth suite is green (14/0/0) against the deployed config.

Nothing left on the mvsMF side. The only remaining item here is the
samplib/httpprm0 documented example for the ordering rule.