Skip to content

Hub API authentication and authorization

How a Hub API caller authenticates, which role each route needs, and how browser writes carry the CSRF token. Request validation and the site endpoints are in Site management.

Authorization

Authentication

require_login and optional_login are UI-only. API routes use the API authorization decorator instead. It runs an authentication chain and then a role check (core/src/ecmwf/sites/core/auth/authn.py, authz.py):

Handler Credential Identity when accepted
NoAuthHandler none (anonymous routes only) anonymous role
SitesHubMasterTokenHandler platform master token (hub.master_token) the api-administration-token user, with the platform administrator and staff policies
SitesSiteMasterTokenHandler Site master token, on /hub/api/v*/sites/<space>/<site>/… paths only the master-token user, with the Site's administrator and access groups
OIDCTokenHandler bearer token in the Authorization header the provider user and policies
CookieHandler Hub session cookie the signed-in browser user

Bearer values in query parameters and form fields are not accepted: the token handlers read only the Authorization header, and the code documents query and form token transport as intentionally ignored. Token comparison for the master-token handlers is constant-time. Detailed token semantics and the proxy-side rules are in security design.

Roles

Each API route selects one authorization instance: anonymous (any authenticated identity, or anonymous where the chain allows it), staff, or platform administrator. Unauthenticated calls answer 401 with a WWW-Authenticate: Bearer header; authenticated calls with an insufficient role answer 403. Site-scoped handlers add a third layer inside the handler: site.get_access_management().is_current_user_admin (Site administrators by user and group lists, plus platform administrators), which answers 403.

The authorization layer distinguishes:

  • Site owners and administrators, who manage the Site and its credentials;
  • staff users, who can view content and use permitted staff operations;
  • platform administrators, who can perform platform-wide actions;
  • users and groups selected by Site access settings.

The Site resource supplies the access data used by the Hub and by the Site configuration.

CSRF

The Hub enforces a CSRF token for browser writes. A request with an unsafe method (POST, PUT, PATCH, DELETE) that presents the Hub session cookie must also present the session-bound token, in the X-CSRF-Token header or the csrf_token form field; otherwise the Hub answers 403. Bearer requests are exempt: API clients send no cookie, and a cross-site request cannot set the Authorization header. The token is generated per session on first use, and compared in constant time (hub/src/ecmwf/sites/hub/csrf.py, registered as a before_request rule). The session cookie itself is named __Host-sites-hub (SESSION_COOKIE_NAME, core/.../config/flask.py); the CSRF exemption above keys on that name. The __Host- prefix makes the browser accept the cookie only with Secure, Path=/, and no Domain, so a sibling host cannot set or overwrite it. The web interface carries the token automatically: pages render it in a meta tag and a script adds the header to every non-GET jQuery request; HTML forms render a hidden input (hub/tests/test_csrf.py covers the rule).