fix(auth_n): try refresh oidc client on token exchange failure

.env.example

@@ -36,6 +36,27 @@ AUTH_PROVIDER=DISABLED
 # OIDC_REDIRECT_HOST="http://localhost:8080"
 # OIDC_ORG_TOKEN_ENDPOINT_FORMAT="http://localhost:8081/realms/<organisation>/protocol/openid-connect/token"
 # OIDC_ORG_ISSUER_ENDPOINT_FORMAT="http://localhost:8081/realms/<organisation>"
+### Env(s) for optional API-token auth via RFC 7662 introspection (OIDC only)
+### Present all required vars to enable. See docs: Self-Hosting > Authentication.
+# OIDC_API_TOKEN_PREFIX=apikey                    # arbitrary, operator-chosen; marks a bearer token as an API key
+# OIDC_API_TOKEN_DELIMITER=_                       # optional separator; defaults to "_"
+### The flow needs the prefix plus at least ONE validation mechanism below:
+### static tokens and/or RFC 7662 introspection (static tokens are tried first).
+### (1) Static tokens: KMS-encrypted JSON array; each maps to a fixed principal
+###     (and, in SaaS, an "org"; omit "org" for a global-scoped token).
+# OIDC_API_STATIC_TOKENS='[{"token":"s3cr3t-ci","principal":"svc-ci","org":"acme"}]'
+### (2) RFC 7662 introspection caller auth: verbatim Authorization header
+###     (Bearer/Basic); secret, KMS-encrypted in non-dev.
+# OIDC_INTROSPECTION_AUTH_HEADER="Bearer introspect_secret"
+### Endpoint URLs below are OPTIONAL: when unset, the introspection endpoint is
+### discovered from provider metadata. The SaaS per-org format is the exception
+### (not discoverable) and is required for org-scoped API tokens.
+### Simple OIDC: single endpoint (optional; discovered otherwise)
+# OIDC_TOKEN_INTROSPECTION_URL="http://localhost:8081/realms/users/protocol/openid-connect/token/introspect"
+### SaaS OIDC: per-org format is REQUIRED (global-only is rejected at startup);
+### OIDC_TOKEN_INTROSPECTION_URL is an optional global (Login::Global) override.
+# OIDC_ORG_TOKEN_INTROSPECTION_URL_FORMAT="http://localhost:8081/realms/<organisation>/protocol/openid-connect/token/introspect"
+# OIDC_TOKEN_INTROSPECTION_URL="http://localhost:8081/realms/users/protocol/openid-connect/token/introspect"
 AUTH_Z_PROVIDER=DISABLED
 ### Env(s) for Casbin AuthZ
 # AUTH_Z_PROVIDER=CASBIN
@@ -59,24 +80,6 @@ REDIS_KEY_TTL=604800
 # Workspace lock TTL for batch operations in milliseconds (default: 1200000 = 20min)
 # WORKSPACE_LOCK_BATCH_TTL_MS=1200000
 
-################################################
-## Following values are to be set in KMS and not directly in ENV
-#
-# DB_PASSWORD
-# SUPERPOSITION_TOKEN
-# KRONOS_DISPATCH_TOKEN - scoped token for Kronos webhook callbacks (dispatch endpoint only)
-# OIDC_CLIENT_SECRET - if using OIDC as authn provider
-# CASBIN_DB_PASSWORD - if using CASBIN as authz provider
-# MASTER_ENCRYPTION_KEY - for using secrets
-# PREVIOUS_MASTER_ENCRYPTION_KEY - needed for rotating secrets
-#
-# also include the keys in KMS which have been mentioned in ENCRYPTED_KEYS
-#
-#
-## for local development, they already have a default value,
-## to override, you can set them directly in .env file
-#################################################
-
 ## used for internal admin operations like log level changes
 # INTERNAL_OPS_API_KEY = ""
 
@@ -92,4 +95,21 @@ KRONOS_ENCRYPTION_KEY="5d5e2e704c866bddeb6dd7ef1ea69f39a6eb3934f60e3f13f67c605b5
 KRONOS_DB_POOL_SIZE="1"
 
 # Needed for both service and library mode, but only in DEV/TEST. In production, this is stored in KMS.
-KRONOS_DISPATCH_TOKEN="dispatch-test"
+KRONOS_DISPATCH_TOKEN="dispatch-test"
+
+################################################
+## Following values are to be set in KMS and not directly in ENV
+#
+# DB_PASSWORD
+# SUPERPOSITION_TOKEN
+# KRONOS_DISPATCH_TOKEN - scoped token for Kronos webhook callbacks (dispatch endpoint only)
+# OIDC_CLIENT_SECRET - if using OIDC as authn provider
+# OIDC_INTROSPECTION_AUTH_HEADER - if using API-token (RFC 7662) introspection
+# OIDC_API_STATIC_TOKENS - if using API-token static tokens
+# CASBIN_DB_PASSWORD - if using CASBIN as authz provider
+# MASTER_ENCRYPTION_KEY - for using secrets
+# PREVIOUS_MASTER_ENCRYPTION_KEY - needed for rotating secrets
+#
+## for local development, they already have a default value,
+## to override, you can set them directly in .env file
+#################################################

crates/service_utils/src/db/utils.rs

@@ -45,6 +45,53 @@ pub async fn get_oidc_client_secret(
     }
 }
 
+/// The verbatim `Authorization` header value Superposition presents to the RFC
+/// 7662 introspection endpoint (e.g. `Bearer <token>` or `Basic <base64>`).
+/// This is a secret and is KMS-decrypted like other secrets in non-dev
+/// environments. Returns `None` when the (optional) API-token flow is not
+/// configured.
+pub async fn get_introspection_auth_header(
+    kms_client: &Option<Client>,
+    app_env: &AppEnv,
+) -> Option<String> {
+    if std::env::var("OIDC_INTROSPECTION_AUTH_HEADER").is_err() {
+        return None;
+    }
+    match app_env {
+        AppEnv::DEV | AppEnv::TEST | AppEnv::SANDBOX => {
+            std::env::var("OIDC_INTROSPECTION_AUTH_HEADER").ok()
+        }
+        _ => Some(
+            kms::decrypt(
+                kms_client.clone().unwrap(),
+                "OIDC_INTROSPECTION_AUTH_HEADER",
+            )
+            .await,
+        ),
+    }
+}
+
+/// The JSON array of static API tokens (`OIDC_API_STATIC_TOKENS`), each entry
+/// `{token, principal[, email, org]}`. A secret, KMS-decrypted like other
+/// secrets in non-dev environments. Returns `None` when unset (static-token
+/// mechanism disabled).
+pub async fn get_static_api_tokens(
+    kms_client: &Option<Client>,
+    app_env: &AppEnv,
+) -> Option<String> {
+    if std::env::var("OIDC_API_STATIC_TOKENS").is_err() {
+        return None;
+    }
+    match app_env {
+        AppEnv::DEV | AppEnv::TEST | AppEnv::SANDBOX => {
+            std::env::var("OIDC_API_STATIC_TOKENS").ok()
+        }
+        _ => Some(
+            kms::decrypt(kms_client.clone().unwrap(), "OIDC_API_STATIC_TOKENS").await,
+        ),
+    }
+}
+
 pub async fn get_kronos_api_key(kms_client: &Option<Client>, app_env: &AppEnv) -> String {
     match app_env {
         AppEnv::DEV | AppEnv::TEST => {