gea-program 0.55.0__tar.gz → 0.56.0__tar.gz

{gea_program-0.55.0/gea_program.egg-info → gea_program-0.56.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.55.0
+Version: 0.56.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -1272,6 +1272,25 @@ Or Administration -> **HTTPS** in the page (download the certificate, not
 the key, for the site's computers to trust; compare the SHA-256 shown).
 `gea help https`.
 
+### Company sign-in
+
+People sign in with the account the company already manages - Microsoft
+Entra ID, Okta, Google Workspace, Ping, Keycloak, AD FS - by OpenID Connect
+(the authorization code flow with PKCE), so the company's multi-factor,
+conditional access and leavers apply. The ID token is checked with the
+standard library alone (its RS256 signature against the provider's
+published keys, the issuer, the audience, the times, the nonce); the role in
+GEA is the highest any of the person's app roles or groups maps to. Local
+accounts stay, for the first administrator and for when the provider cannot
+be reached. HTTPS comes first (above).
+
+```
+gea oidc --workspace C:\site --issuer https://login.microsoftonline.com/3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64/v2.0 --client-id a41c7e92-0d3b-4f6a-9e85-2b6d1c4f7a30 --redirect-uri https://gea-pad3.example.local:8765/api/oidc/callback --secret-from-env GEA_OIDC_SECRET --map GEA.Operator=operator --map GEA.Admin=admin --test
+```
+
+Or Administration -> **Company sign-in**. `gea help company-sign-in` has the
+Entra ID app registration step by step.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: HTTPS from the service itself (above),

{gea_program-0.55.0 → gea_program-0.56.0}/README.md

@@ -1233,6 +1233,25 @@ Or Administration -> **HTTPS** in the page (download the certificate, not
 the key, for the site's computers to trust; compare the SHA-256 shown).
 `gea help https`.
 
+### Company sign-in
+
+People sign in with the account the company already manages - Microsoft
+Entra ID, Okta, Google Workspace, Ping, Keycloak, AD FS - by OpenID Connect
+(the authorization code flow with PKCE), so the company's multi-factor,
+conditional access and leavers apply. The ID token is checked with the
+standard library alone (its RS256 signature against the provider's
+published keys, the issuer, the audience, the times, the nonce); the role in
+GEA is the highest any of the person's app roles or groups maps to. Local
+accounts stay, for the first administrator and for when the provider cannot
+be reached. HTTPS comes first (above).
+
+```
+gea oidc --workspace C:\site --issuer https://login.microsoftonline.com/3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64/v2.0 --client-id a41c7e92-0d3b-4f6a-9e85-2b6d1c4f7a30 --redirect-uri https://gea-pad3.example.local:8765/api/oidc/callback --secret-from-env GEA_OIDC_SECRET --map GEA.Operator=operator --map GEA.Admin=admin --test
+```
+
+Or Administration -> **Company sign-in**. `gea help company-sign-in` has the
+Entra ID app registration step by step.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: HTTPS from the service itself (above),

{gea_program-0.55.0 → gea_program-0.56.0}/gea/__init__.py

@@ -123,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.55.0"
+__version__ = "0.56.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.55.0 → gea_program-0.56.0}/gea/__main__.py

@@ -776,6 +776,24 @@ def main(argv=None) -> int:
     p_tl.add_argument("--actor", type=str, default="cli")
     p_tl.add_argument("--json", action="store_true")
 
+    p_oc = sub.add_parser("oidc", help="company sign-in (OpenID Connect: Entra ID, Okta, Google, Ping, Keycloak, AD FS): set it, test the provider, remove it; with no option, how it stands")
+    p_oc.add_argument("--workspace", type=str, required=True)
+    p_oc.add_argument("--issuer", type=str, default=None, help="Entra ID: https://login.microsoftonline.com/3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64/v2.0")
+    p_oc.add_argument("--client-id", type=str, default=None)
+    p_oc.add_argument("--redirect-uri", type=str, default=None, help="https://gea-pad3.example.local:8765/api/oidc/callback, registered with the provider exactly")
+    p_oc.add_argument("--secret-from-env", type=str, default=None, help="read the client secret from this environment variable now and keep it in keys\\oidc_client_secret.txt")
+    p_oc.add_argument("--secret-env", type=str, default=None, help="or: the service reads the client secret from this environment variable at each sign-in (nothing kept)")
+    p_oc.add_argument("--role-claim", type=str, default=None, help="roles (Entra ID app roles, the default) or groups, or any claim")
+    p_oc.add_argument("--map", action="append", default=[], help="VALUE=ROLE, e.g. GEA.Admin=admin (repeat)")
+    p_oc.add_argument("--default-role", type=str, default=None, help="the role of a person with no mapped value; 'none' (the default) means no sign-in")
+    p_oc.add_argument("--name-claim", type=str, default=None, help="the claim that names the person (preferred_username by default)")
+    p_oc.add_argument("--label", type=str, default=None, help="the sign-in button's words")
+    p_oc.add_argument("--pause", action="store_true", help="keep the settings, stop company sign-in")
+    p_oc.add_argument("--test", action="store_true", help="read the provider's discovery document and keys now")
+    p_oc.add_argument("--off", action="store_true", help="remove company sign-in (local accounts are unchanged)")
+    p_oc.add_argument("--actor", type=str, default="cli")
+    p_oc.add_argument("--json", action="store_true")
+
     p_hk = sub.add_parser("housekeeping", help="rotate the append-only logs, prune finished job folders and old live recordings (dry run unless --apply)")
     p_hk.add_argument("--workspace", type=str, required=True)
     p_hk.add_argument("--apply", action="store_true")
@@ -2616,6 +2634,53 @@ def main(argv=None) -> int:
             raise SystemExit(f"pore-pressure: {e.args[0] if e.args else e}")
         print(_json.dumps(r, default=str) if a.json else _PPF.text(r))
         return 0
+    elif a.cmd == "oidc":
+        import json as _json
+        from . import oidc as _OI
+        from .workspace import Workspace, WorkspaceError
+        try:
+            ws = Workspace(a.workspace)
+            changing = any(x is not None for x in (a.issuer, a.client_id, a.redirect_uri, a.secret_from_env, a.secret_env, a.role_claim,
+                                                   a.default_role, a.name_claim, a.label)) or a.map or a.pause
+            if a.off:
+                r = _OI.turn_off(ws, a.actor)
+            elif changing:
+                cur = _OI.settings(ws) or {}
+                s = {k: cur.get(k, v) for k, v in _OI.DEFAULTS.items()}
+                for k, v in (("issuer", a.issuer), ("client_id", a.client_id), ("redirect_uri", a.redirect_uri), ("role_claim", a.role_claim),
+                             ("name_claim", a.name_claim), ("label", a.label), ("client_secret_env", a.secret_env)):
+                    if v is not None:
+                        s[k] = v
+                if a.default_role is not None:
+                    s["default_role"] = None if a.default_role.lower() in ("", "none") else a.default_role
+                if a.map:
+                    m = {}
+                    for x in a.map:
+                        v_, _, r_ = x.rpartition("=")
+                        if not v_:
+                            raise ValueError(f"--map takes VALUE=ROLE, not {x!r}")
+                        m[v_.strip()] = r_.strip()
+                    s["role_map"] = m
+                if a.secret_from_env:
+                    s["client_secret_env"] = ""
+                s["enabled"] = not a.pause
+                sec = None
+                if a.secret_from_env:
+                    sec = os.environ.get(a.secret_from_env, "")
+                    if not sec:
+                        raise ValueError(f"the environment variable {a.secret_from_env} is empty")
+                r = _OI.configure(ws, a.actor, s, sec)
+            else:
+                r = _OI.status(ws)
+            if a.test:
+                r = {**r, "test": _OI.test(ws)}
+        except (KeyError, ValueError, OSError, WorkspaceError) as e:
+            raise SystemExit(f"oidc: {e.args[0] if e.args else e}")
+        if a.json:
+            print(_json.dumps(r, default=str))
+        else:
+            print(_OI.text(r))
+        return 0
     elif a.cmd == "tls":
         import json as _json
         from . import tls as _TLS

{gea_program-0.55.0 → gea_program-0.56.0}/gea/acceptance_tests.py

@@ -12461,6 +12461,205 @@ def section_cx_https(tmp: str) -> None:
        "no dossier carries the key; the help page" + (f" - failed: {failed4}" if failed4 else ""))
 
 
+def section_cy_company_sign_in(tmp: str) -> None:
+    """Section CY - company sign-in (OpenID Connect): against a stand-in provider over HTTPS, the whole browser round
+    trip - the start, the provider, the code exchanged with PKCE and the secret, the ID token checked, the role from the
+    claims, a session - and every way an ID token or a return can be wrong turned away; the company account beside the
+    local ones; the settings, the secret kept out of sight; the CLI, the page and the help."""
+    import http.client
+    import ssl as _ssl
+    import subprocess as _sp
+    import urllib.parse as _up
+    import zipfile as _zf
+    from . import __version__ as _ver
+    from . import dossier as DZ
+    from . import helplib as H
+    from . import oidc as OI
+    from . import tls as TLS
+    from .oidc_mock import MockIdP
+    from .service import Service, Users
+    from .workspace import Workspace
+    pkg = Path(__file__).parent
+    idp = MockIdP()
+    wsp = str(Path(tmp, "ws_cy")); ws = Workspace.create(wsp, "Company Site", actor="tester")
+    users = Users(str(Path(wsp, "users.json")))
+    users.add("adm", "admin-pass-123", "admin"); users.add("v", "viewer-pass-1", "viewer"); users.add("olga.local", "local-pass-12", "operator")
+    TLS.make_self_signed(ws, "tester", ["localhost", "127.0.0.1"], days=60)
+    svc = Service(wsp, host="127.0.0.1", port=0, scheduler=False)
+    svc.app.oidc_ssl_context = idp.client_ctx
+    svc.start()
+    base = svc.url.rstrip("/")
+    trust = _ssl.create_default_context(cafile=str(Path(wsp, TLS.SELF_CERT)))
+
+    def get(url, cookie=None, ctx=trust):
+        u = _up.urlsplit(url)
+        c = http.client.HTTPSConnection(u.hostname, u.port, context=ctx, timeout=30)
+        c.request("GET", u.path + ("?" + u.query if u.query else ""), headers=({"Cookie": cookie} if cookie else {}))
+        r = c.getresponse()
+        b = r.read()
+        c.close()
+        return r.status, r.getheader("Location"), r.headers.get_all("Set-Cookie") or [], b
+
+    def api(method, path, body=None, cookie=None):
+        c = http.client.HTTPSConnection("127.0.0.1", svc.port, context=trust, timeout=30)
+        h = {"Content-Type": "application/json", "X-GEA-Action": "1"} if method == "POST" else {}
+        if cookie:
+            h["Cookie"] = cookie
+        c.request(method, path, body=(json.dumps(body) if body is not None else None), headers=h)
+        r = c.getresponse()
+        b = r.read()
+        c.close()
+        return r.status, json.loads(b or b"{}"), r.headers.get_all("Set-Cookie") or []
+
+    def local(name, pw):
+        return [x for x in api("POST", "/api/login", {"name": name, "password": pw})[2] if x.startswith("gea_session")][0].split(";")[0]
+
+    def round_trip(user=None, fault=None, keep_cookie=True):
+        """The browser's path: start -> the provider -> back. (status, the page, the session cookie or None, the callback URL, the flow cookie)"""
+        idp.fault = fault
+        if user:
+            idp.user = user
+        s1, loc1, ck1, _ = get(base + "/api/oidc/start")
+        flow = ck1[0].split(";")[0] if ck1 else None
+        s2, loc2, _, _ = get(loc1, ctx=idp.client_ctx)
+        s3, _, ck3, b3 = get(loc2, cookie=(flow if keep_cookie else None))
+        sess = next((x.split(";")[0] for x in ck3 if x.startswith("gea_session=") and not x.startswith("gea_session=;")), None)
+        return s3, b3.decode("utf-8", "replace"), sess, loc2, flow, (s1, s2, ck1)
+    olga = {"sub": "sub-olga", "preferred_username": "olga@example.com", "roles": ["GEA.Operator"]}
+    try:
+        adm = local("adm", "admin-pass-123"); vw = local("v", "viewer-pass-1")
+        # -- CY1 the settings --------------------------------------------------------------------------------------------
+        redir = base + "/api/oidc/callback"
+        good = {"issuer": idp.issuer, "client_id": idp.client_id, "redirect_uri": redir,
+                "role_map": {"GEA.Viewer": "viewer", "GEA.Operator": "operator", "GEA.Approver": "approver", "GEA.Admin": "admin"}}
+        bad = [{**good, "redirect_uri": "http://gea-pad3.example.local:8765/api/oidc/callback"}, {**good, "redirect_uri": base + "/somewhere"},
+               {**good, "issuer": "https://login.microsoftonline.com/common/v2.0"}, {**good, "issuer": "http://idp.example"},
+               {**good, "role_map": {}}, {**good, "role_map": {"x": "superuser"}}, {**good, "client_id": ""}]
+        bad_codes = [api("POST", "/api/oidc", {"action": "set", **b, "client_secret": "s"}, adm)[0] for b in bad]
+        s_vset = api("POST", "/api/oidc", {"action": "set", **good, "client_secret": idp.client_secret}, vw)[0]
+        s_set, st_set, _ = api("POST", "/api/oidc", {"action": "set", **good, "client_secret": idp.client_secret}, adm)
+        s_get, st_get, _ = api("GET", "/api/oidc", cookie=adm)
+        s_vget = api("GET", "/api/oidc", cookie=vw)[0]
+        s_test, tst, _ = api("POST", "/api/oidc", {"action": "test"}, adm)
+        sess_pub = api("GET", "/api/session")[1]
+        secret_file = Path(wsp, OI.SECRET_FILE)
+        c1 = {
+            "refused": all(c == 400 for c in bad_codes) and s_vset == 403 and s_vget == 403,
+            "kept": s_set == 200 and st_set["configured"] and st_set["secret"] == "kept" and s_get == 200 and st_get["issuer"] == idp.issuer
+                    and idp.client_secret not in json.dumps(st_get) and secret_file.read_text(encoding="utf-8") == idp.client_secret
+                    and (os.name == "nt" or (secret_file.stat().st_mode & 0o077) == 0),
+            "test": s_test == 200 and tst["ok"] and tst["signing_keys"] == 1 and tst["token_endpoint"].endswith("/token"),
+            "public": sess_pub.get("company_sign_in") == {"label": "Sign in with your company account"} and sess_pub.get("user") is None,
+        }
+        failed1 = [k for k, v in c1.items() if not v]
+        ok(not failed1,
+           "CY1 company sign-in is set by an administrator only: an http:// or wrong redirect URI, a multi-tenant issuer, an issuer not on https, no role map "
+           "and no default, a role that does not exist, no client id - each refused; the secret is kept in keys\\ readable by its owner only and never sent "
+           "back; Test reads the provider's discovery and keys; the sign-in page learns only that the button exists" + (f" - failed: {failed1}" if failed1 else ""))
+        # -- CY2 the round trip --------------------------------------------------------------------------------------------
+        s3, page, sess, cb_url, flow, (s1, s2, ck1) = round_trip(olga)
+        me = api("GET", "/api/session", cookie=sess)[1]["user"] if sess else {}
+        call = idp.token_calls[-1] if idp.token_calls else {}
+        r_replay = get(cb_url, cookie=flow)
+        s_replay, replay_body = r_replay[0], r_replay[3].decode()
+        idp.user = dict(olga, roles=["GEA.Operator", "GEA.Admin"])
+        s_up, _, sess_up, _, _, _ = round_trip()
+        me_up = api("GET", "/api/session", cookie=sess_up)[1]["user"] if sess_up else {}
+        listed = {u["name"]: u for u in api("GET", "/api/users", cookie=adm)[1]["users"]}
+        live = [x for x in api("GET", "/api/sessions", cookie=adm)[1]["sessions"] if x["name"] == "olga@example.com"]
+        c2 = {
+            "start": s1 == 302 and "SameSite=Lax" in ck1[0] and "Secure" in ck1[0] and "Path=/api/oidc" in ck1[0] and s2 == 302,
+            "back": s3 == 200 and 'http-equiv="refresh"' in page and sess is not None and me.get("name") == "olga@example.com" and me.get("role") == "operator"
+                    and me.get("via") == "company",
+            "pkce": call.get("code_verifier") and call.get("client_secret") == idp.client_secret and call.get("redirect_uri") == redir,
+            "once": s_replay == 401 and "unknown or has expired" in replay_body,
+            "role_follows": me_up.get("role") == "admin" and listed["olga@example.com"]["kind"] == "company" and listed["olga@example.com"]["role"] == "admin"
+                            and live and all(x["via"] == "company" for x in live),
+        }
+        failed2 = [k for k, v in c2.items() if not v]
+        ok(not failed2,
+           "CY2 the round trip: the start sends the browser to the provider with a flow cookie (SameSite=Lax, Secure, this path only); back with a code, the "
+           "service exchanges it with the client secret and the PKCE verifier, checks the ID token, and the person is signed in as a company account with the "
+           "role their claims map to - the highest, taken again at every sign-in - by a page that moves on by itself (the session cookie stays Strict); "
+           "a return is accepted once" + (f" - failed: {failed2}" if failed2 else ""))
+        # -- CY3 every way it can be wrong ----------------------------------------------------------------------------------
+        outcomes = {}
+        for f in ("aud", "expired", "sig", "alg_none", "hs256", "nonce", "iss"):
+            st_, pg_, se_, _, _, _ = round_trip(olga, fault=f)
+            outcomes[f] = (st_, se_ is None, pg_)
+        st_rot, _, se_rot, _, _, _ = round_trip(olga, fault="rotate")
+        st_nb, pg_nb, se_nb, _, _, _ = round_trip(olga, keep_cookie=False)
+        st_nr, pg_nr, se_nr, _, _, _ = round_trip({"sub": "sub-x", "preferred_username": "x@example.com", "roles": ["Other"]})
+        st_lc, pg_lc, se_lc, _, _, _ = round_trip({"sub": "sub-l", "preferred_username": "olga.local", "roles": ["GEA.Admin"]})
+        st_os, pg_os, se_os, _, _, _ = round_trip({"sub": "someone-else", "preferred_username": "olga@example.com", "roles": ["GEA.Admin"]})
+        pg_ov = ""
+        try:
+            OI.role_of({"_claim_names": {"groups": "src1"}}, {**OI.DEFAULTS, "role_claim": "groups", "role_map": {"g": "viewer"}})
+        except OI.OidcError as e:
+            pg_ov = str(e)
+        s_dis = api("POST", "/api/users/disable", {"name": "olga@example.com", "disabled": True}, adm)[0]
+        st_dis, pg_dis, se_dis, _, _, _ = round_trip(olga)
+        api("POST", "/api/users/disable", {"name": "olga@example.com", "disabled": False}, adm)
+        s_pw = api("POST", "/api/users/password", {"name": "olga@example.com", "password": "whatever-123"}, adm)[0]
+        s_role = api("POST", "/api/users/role", {"name": "olga@example.com", "role": "viewer"}, adm)[0]
+        s_pwlogin = api("POST", "/api/login", {"name": "olga@example.com", "password": ""})[0]
+        s_local = api("POST", "/api/login", {"name": "olga.local", "password": "local-pass-12"})[0]
+        audit = Path(ws.audit_path).read_text(encoding="utf-8")
+        why = {"aud": "audience", "expired": "expired", "sig": "signature", "alg_none": "only RS256", "hs256": "only RS256", "nonce": "nonce", "iss": "issued by"}
+        c3 = {
+            "tokens": all(outcomes[f][0] == 401 and outcomes[f][1] and why[f] in outcomes[f][2] for f in why),
+            "rotation": st_rot == 200 and se_rot is not None,
+            "binding": st_nb == 401 and se_nb is None and "another browser" in pg_nb,
+            "no_role": st_nr == 401 and se_nr is None and "no role in GEA" in pg_nr and "Other" in pg_nr,
+            "no_takeover": st_lc == 401 and se_lc is None and "local account" in pg_lc and st_os == 401 and se_os is None and "another company identity" in pg_os,
+            "overage": "more groups than a token carries" in pg_ov,
+            "disabled": s_dis == 200 and st_dis == 401 and se_dis is None and "disabled" in pg_dis,
+            "no_password": s_pw == 400 and s_role == 400 and s_pwlogin in (400, 401) and s_local == 200,
+            "audited": audit.count('"via": "company"') >= 3 and '"login.failed"' in audit and "audience" in audit,
+        }
+        failed3 = [k for k, v in c3.items() if not v]
+        ok(not failed3,
+           "CY3 turned away, each saying why, with no session: an ID token for another application, expired, with a bad signature, signed 'none' or HS256, "
+           "with another sign-in's nonce, from another issuer; a return to a browser that did not start the sign-in; a person with no mapped role; a name "
+           "a local account has, or a company account bound to another subject; a person in more groups than a token carries; a company account disabled "
+           "in GEA. A rotated signing key is fetched and accepted. A company account has no password here and its role is not set by hand; local accounts "
+           "sign in as before; every sign-in and failure is audited" + (f" - failed: {failed3}" if failed3 else ""))
+    finally:
+        svc.stop()
+    # -- CY4 the CLI, the dossier, the page, the help -------------------------------------------------------------------
+    env = {**os.environ, "GEA_OIDC_TEST_SECRET": "cli-secret-456", "SSL_CERT_FILE": idp.cafile}
+    w2 = str(Path(tmp, "ws_cy2")); Workspace.create(w2, "CLI Site", actor="tester")
+    cli_set = _sp.run([sys.executable, "-m", "gea", "oidc", "--workspace", w2, "--issuer", idp.issuer, "--client-id", idp.client_id,
+                       "--redirect-uri", "https://gea-pad3.example.local:8765/api/oidc/callback", "--secret-from-env", "GEA_OIDC_TEST_SECRET",
+                       "--map", "GEA.Admin=admin", "--map", "GEA.Viewer=viewer", "--default-role", "none", "--test"],
+                      capture_output=True, text=True, cwd=str(pkg.parent), env=env)
+    cli_st = _sp.run([sys.executable, "-m", "gea", "oidc", "--workspace", w2, "--json"], capture_output=True, text=True, cwd=str(pkg.parent), env=env)
+    cli_bad = _sp.run([sys.executable, "-m", "gea", "oidc", "--workspace", w2, "--map", "nonsense"], capture_output=True, text=True, cwd=str(pkg.parent), env=env)
+    cli_off = _sp.run([sys.executable, "-m", "gea", "oidc", "--workspace", w2, "--off"], capture_output=True, text=True, cwd=str(pkg.parent), env=env)
+    idp.stop()
+    __import__("gea.frac_hits", fromlist=["write_report"]).write_report(ws, _ver, "tester")
+    dz = DZ.build(ws, "tester", _ver, None, include_sources=True)
+    with _zf.ZipFile(Path(ws.reports_dir, dz["path"])) as z:
+        leaked = [n for n in z.namelist() if idp.client_secret.encode() in z.read(n)]
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    st_cli = json.loads(cli_st.stdout) if cli_st.returncode == 0 else {}
+    c4 = {
+        "cli": cli_set.returncode == 0 and "provider: GOOD" in cli_set.stdout and "GEA.Admin -> admin" in cli_set.stdout
+               and st_cli.get("secret") == "kept" and Path(w2, OI.SECRET_FILE).read_text(encoding="utf-8") == "cli-secret-456"
+               and "cli-secret-456" not in cli_st.stdout and cli_bad.returncode != 0 and "VALUE=ROLE" in (cli_bad.stderr + cli_bad.stdout)
+               and cli_off.returncode == 0 and "local accounts only" in cli_off.stdout,
+        "dossier": not leaked and idp.client_secret not in Path(ws.audit_path).read_text(encoding="utf-8"),
+        "page": all(x in page_src for x in ("/api/oidc/start", "aCompany", "s.company_sign_in", "ocSave", "ocTest", "ocMap", "company account: role from its claims"))
+                and "[hidden] { display: none !important; }" in page_src,
+        "help": not H.check("company-sign-in") and "Entra" in (H.page("company-sign-in") or "") and "App roles" in (H.page("company-sign-in") or ""),
+    }
+    failed4 = [k for k, v in c4.items() if not v]
+    ok(not failed4,
+       "CY4 `gea oidc` sets company sign-in from a terminal (the secret read from an environment variable once and kept, never printed), tests the "
+       "provider, refuses a malformed map and removes it; no dossier carries the client secret; the sign-in page's button and the Company sign-in card; "
+       "the help page with the Entra ID steps" + (f" - failed: {failed4}" if failed4 else ""))
+
+
 def PR_read_ok(path) -> bool:
     from . import pdf_report as PR
     try:
@@ -12574,6 +12773,7 @@ def main() -> int:
         section_cv_torque_drag(tmp)
         section_cw_decline(tmp)
         section_cx_https(tmp)
+        section_cy_company_sign_in(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.55.0 → gea_program-0.56.0}/gea/doctor.py

@@ -257,7 +257,7 @@ def check_workspace(path: str, host: str = '127.0.0.1', port: int = 8765) -> Lis
         from . import tls as TLS
         ts = TLS.status(ws)
         lvl = {'OFF': 'info', 'OK': 'ok', 'EXPIRING': 'warn', 'EXPIRED': 'warn', 'NOT_YET_VALID': 'warn', 'BROKEN': 'block'}[ts['state']]
-        fix = {'OFF': f'for the site network: gea tls --workspace "{path}" --site-cert <the .crt or .pem> --site-key <its key>, or --self-signed',
+        fix = {'OFF': f'for the site network: gea tls --workspace "{path}" --site-cert C:\\certs\\gea-pad3.crt --site-key C:\\certs\\gea-pad3.key, or --self-signed',
                'EXPIRING': f'gea tls --workspace "{path}" shows the certificate; renew it (or --self-signed for a new one) and restart',
                'EXPIRED': f'gea tls --workspace "{path}" --self-signed makes a new one; a site certificate is renewed by the site',
                'NOT_YET_VALID': "set this machine's clock",

gea_program-0.56.0/gea/help/company-sign-in.md

@@ -0,0 +1,19 @@
+# Company sign-in
+
+> People sign in to the control panel with the account the company already manages - Microsoft Entra ID, Okta, Google Workspace, Ping, Keycloak or AD FS, by OpenID Connect - so the company's multi-factor, conditional access and leavers apply; the role in GEA comes from the app roles or groups the company gives them. Local accounts stay.
+
+**The command**: Administration -> **Company sign-in** (the administrator role): the issuer, the client id and secret, the redirect URI, the role claim and the role map, a default role, the claim that names the person, the button's words; **Save**, **Test the provider**, **Remove company sign-in**. The sign-in page then shows the button above the local sign-in. From a terminal: `gea oidc --workspace C:\site` prints how it stands; `--issuer https://login.microsoftonline.com/3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64/v2.0 --client-id a41c7e92-0d3b-4f6a-9e85-2b6d1c4f7a30 --redirect-uri https://gea-pad3.example.local:8765/api/oidc/callback --secret-from-env GEA_OIDC_SECRET --map GEA.Viewer=viewer --map GEA.Operator=operator --map GEA.Approver=approver --map GEA.Admin=admin` sets it (the secret is read from that environment variable once and kept; `--secret-env NAME` has the service read it at every sign-in instead); `--test` reads the provider; `--pause`; `--off`.
+
+**What it needs**: HTTPS on first (`gea help https`): a provider sends people back only to an https:// address (Entra ID allows http only for localhost). The machine running the service reaches the provider over HTTPS (Entra ID: `login.microsoftonline.com`), and its clock is right to within five minutes. For **Microsoft Entra ID**: in the Entra admin center, App registrations -> New registration - a name ("GEA control panel"), accounts in this organizational directory only, Redirect URI of the Web platform: the control panel's address followed by `/api/oidc/callback`, exactly. Its Overview gives the Application (client) ID and the Directory (tenant) ID: the issuer is `https://login.microsoftonline.com/`, the tenant ID, then `/v2.0` - for a tenant ID of 3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64, `https://login.microsoftonline.com/3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64/v2.0`. Certificates & secrets -> New client secret: its Value, shown once, is the client secret (it expires: set a reminder to renew it). App roles -> four roles, allowed member types Users/Groups, values `GEA.Viewer`, `GEA.Operator`, `GEA.Approver`, `GEA.Admin`. Enterprise applications -> the same application -> Users and groups: assign people or groups a role (assigning a group needs Entra ID P1 or P2), and under Properties set Assignment required, so only those assigned can sign in. Other providers: an OpenID Connect web application (a confidential client with a secret), the authorization code flow, the same redirect URI, ID tokens signed RS256, and a claim carrying the person's roles or groups.
+
+**How it is read**: "Sign in with your company account" sends the browser to the provider with a fresh state, a nonce and a PKCE challenge (S256); a short-lived cookie binds that sign-in to the browser that started it. The provider sends the browser back with a code, which the service exchanges for an ID token with the client secret and the PKCE verifier, server to server. The ID token is checked with nothing outside the standard library: its RS256 signature against the provider's published keys (fetched again once when a token names a key not yet seen, which is how a provider rotates its keys), the issuer, the audience (this client), the expiry, the issue and not-before times (five minutes of clock difference allowed) and the nonce; any other algorithm, `none` included, is turned away, as is a state used twice or more than ten minutes old. The role is the highest any of the person's values in the role claim maps to; no mapped value and no default role, no sign-in, and the page says which values the person had. With the groups claim, Entra ID sends group object IDs (or the on-premises names for synced groups), and none at all for a person in more than 200 groups - app roles avoid both. The person is kept as a company account in `users.json`, named by the name claim and bound to the provider's subject: it has no password here, its role is set from the claims at every sign-in, an administrator can disable it in GEA, and a local account of the same name is never taken over. A failed company sign-in is audited with its reason; it does not count toward the local sign-in lock (the provider keeps its own), so a mistake in the role map cannot lock an office's local accounts out.
+
+**What it writes**: the settings in `workspace.json` (`control.oidc`) with the audit line `oidc.settings` (and `oidc.off`); the client secret in `keys\oidc_client_secret.txt` (readable by its owner only; never shown, never in a report, an export or a dossier, sent only to the token endpoint) unless an environment variable is named; each sign-in as the audit line `login` with `via: company` and the claim values used, each failure as `login.failed` with the reason; the company accounts in `users.json`.
+
+**The number to check**: **Test the provider** - GOOD, with at least one signing key and RS256 among the algorithms; then a sign-in from a private window by a person with each role, and the role shown at the top right against the role assigned in the company directory.
+
+**What this page will not call a measurement**: who a person is - the company's directory says that, and GEA keeps what its signed token said at the moment they signed in. A person removed from the directory keeps a session already open here until it ends (12 hours) or an administrator revokes it under Live sessions.
+
+**Sources**: OpenID Connect Core 1.0 (sections 3.1 and 3.1.3.7: the authorization code flow and the ID token's checks); RFC 6749 (OAuth 2.0) and RFC 7636 (PKCE); RFC 7515, 7517 and 7518 (JWS, JWK, the RS256 algorithm); RFC 8414 and OpenID Connect Discovery 1.0 (the discovery document); Microsoft, "Redirect URI (reply URL) outline and restrictions" (https required except localhost; at most 256 characters); Microsoft, "Configure group claims for applications by using Microsoft Entra ID" (at most 200 groups in a JWT, object IDs by default).
+
+Related: `gea help https`, `gea help site`, `gea help upkeep`.

{gea_program-0.55.0 → gea_program-0.56.0}/gea/helplib.py

@@ -85,6 +85,7 @@ INDEX: List[tuple] = [
     ('audit-update', 'Audit / Update', 'the whole audit log with filters, the program against PyPI, every report against its source'),
     ('soak', 'The soak', 'the patches through link outages for hours: reconnection, resume, loss by protocol, the page answering - measured, not modelled'),
     ('https', 'HTTPS', "the control panel over HTTPS on the site network: the site's own certificate or a self-signed one made here, the names it carries, handing it out, renewal and the expiry alert"),
+    ('company-sign-in', 'Company sign-in', "people sign in with the account the company manages (Entra ID, Okta, Google, Ping, Keycloak, AD FS by OpenID Connect), the role from its app roles or groups; local accounts stay"),
     ('upkeep', 'Upkeep', 'housekeeping, sessions, the TLS proxy, the load test'),
 ]
 # the four lines every page must carry, in this order