Initial QSfera import

2026-06-07 10:20:04 +03:00
commit 2315f25754
16485 changed files with 4826827 additions and 0 deletions
@@ -0,0 +1,128 @@
+# Webfinger
+
+The webfinger service provides an RFC7033 WebFinger lookup of КуСфера resources, relevant for a given user account at the /.well-known/webfinger enpoint.
+
+1. An [OpenID Connect Discovery](#openid-connect-discovery) for the IdP, based on the КуСфера URL.
+2. An [Authenticated Instance Discovery](#authenticated-instance-discovery), based on the user account.
+
+These two request are only needed for discovery.
+
+## OpenID Connect Discovery
+
+Clients can make an unauthenticated `GET https://drive.qsfera.test/.well-known/webfinger?resource=https%3A%2F%2Fdrive.qsfera.test` request to discover the OpenID Connect Issuer in the `http://openid.net/specs/connect/1.0/issuer` relation:
+
+```json
+{
+    "subject": "https://drive.qsfera.test",
+    "links": [
+        {
+            "rel": "http://openid.net/specs/connect/1.0/issuer",
+            "href": "https://sso.example.org/cas/oidc/"
+        }
+    ]
+}
+```
+
+Here, the `resource` takes the instance domain URI, but an `acct:` URI works as well.
+
+## Authenticated Instance Discovery
+
+When using OpenID connect to authenticate requests, clients can look up the qsfera instances a user has access to.
+
+*   Authentication is necessary to prevent leaking information about existing users.
+*   Basic auth is not supported.
+
+The default configuration will simply return the `OC_URL` and direct clients to that domain:
+
+```json
+{
+    "subject": "acct:alan@drive.qsfera.test",
+    "links": [
+        {
+            "rel": "http://openid.net/specs/connect/1.0/issuer",
+            "href": "https://sso.example.org/cas/oidc/"
+        },
+        {
+            "rel": "http://webfinger.qsfera/rel/server-instance",
+            "href": "https://abc.drive.example.org",
+            "titles": {
+                "en": "КуСфера Instance"
+            }
+        }
+    ]
+}
+```
+
+## Configure Different Instances Based on OpenidConnect UserInfo Claims
+
+A more complex example for configuring different instances could look like this:
+
+```yaml
+webfinger:
+  instances:
+  -  claim: email
+     regex: alan@example\.org
+     href: "https://{{.preferred_username}}.cloud.qsfera.test"
+     title:
+       "en": "КуСфера Instance for Alan"
+       "de": "КуСфера Instanz für Alan"
+     break: true
+  -  claim: "email"
+     regex: mary@example\.org
+     href: "https://{{.preferred_username}}.cloud.qsfera.test"
+     title:
+       "en": "КуСфера Instance for Mary"
+       "de": "КуСфера Instanz für Mary"
+     break: false
+  -  claim: "email"
+     regex: .+@example\.org
+     href: "https://example-org.cloud.qsfera.test"
+     title:
+       "en": "КуСфера Instance for example.org"
+       "de": "КуСфера Instanz für example.org"
+     break: true
+  -  claim: "email"
+     regex: .+@example\.com
+     href: "https://example-com.cloud.qsfera.test"
+     title:
+       "en": "КуСфера Instance for example.com"
+       "de": "КуСфера Instanz für example.com"
+     break: true
+  -  claim: "email"
+     regex: .+@.+\..+
+     href: "https://cloud.qsfera.test"
+     title:
+       "en": "КуСфера Instance"
+       "de": "КуСфера Instanz"
+     break: true
+```
+
+Now, an authenticated webfinger request for `acct:me@example.org` (when logged in as mary) would return two instances, based on her `email` claim, the regex matches and break flags:
+
+```json
+{
+    "subject": "acct:mary@example.org",
+    "links": [
+        {
+            "rel": "http://openid.net/specs/connect/1.0/issuer",
+            "href": "https://sso.example.org/cas/oidc/"
+        },
+        {
+            "rel": "http://webfinger.qsfera/rel/server-instance",
+            "href": "https://mary.cloud.qsfera.test",
+            "titles": {
+                "en": "КуСфера Instance for Mary",
+                "de": "КуСфера Instanz für Mary"
+            }
+        },
+        {
+            "rel": "http://webfinger.qsfera/rel/server-instance",
+            "href": "https://xyz.drive.example.org",
+            "titles": {
+                "en": "КуСфера Instance for example.org",
+                "de": "КуСфера Instanz für example.org"
+            }
+        }
+    ]
+}
+```