Adding the webfinger service

modules/ROOT/pages/deployment/services/s-list/webfinger.adoc

@@ -0,0 +1,144 @@
+= Webfinger Service Configuration
+:toc: right
+:webfinger-url: https://en.wikipedia.org/wiki/WebFinger
+
+:ext_name: webfinger
+
+// remember to REMOVE the corresponding tab if a new ocis release will be published
+
+:no_second_tab: true
+:no_third_tab: true
+
+:description: The Infinite Scale webfinger service provides an RFC7033 WebFinger lookup of ownCloud instances relevant for a given user account.
+
+== Introduction
+
+{description} {webfinger-url}[WebFinger] is a protocol that allows for discovery of information about people and things identified by an URI.
+
+== OpenID Connect Discovery
+
+Clients can make an unauthenticated `GET \https://drive.ocis.test/.well-known/webfinger?resource=https%3A%2F%2Fcloud.ocis.test` request to discover the OpenID Connect Issuer in the `http://openid.net/specs/connect/1.0/issuer` relation:
+
+[source,json]
+----
+{
+    "subject": "acct:[email protected]",
+    "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 owncloud 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 `OCIS_URL` and direct clients to that domain:
+
+[source,json]
+----
+{
+    "subject": "acct:[email protected]",
+    "links": [
+        {
+            "rel": "http://openid.net/specs/connect/1.0/issuer",
+            "href": "https://sso.example.org/cas/oidc/"
+        },
+        {
+            "rel": "http://webfinger.owncloud/rel/server-instance",
+            "href": "https://abc.drive.example.org",
+            "titles": {
+                "en": "oCIS Instance"
+            }
+        }
+    ]
+}
+----
+
+== Configure Different Instances Based on OpenidConnect UserInfo Claims
+
+A more complex example for configuring different instances could look like this:
+
+[source,yaml]
+----
+webfinger:
+  instances:
+  -  claim: email
+     regex: einstein@example\.org
+     href: "https://{{.preferred_username}}.cloud.ocis.test"
+     title: 
+       "en": "oCIS Instance for Einstein"
+       "de": "oCIS Instanz für Einstein"
+     break: true
+  -  claim: "email"
+     regex: marie@example\.org
+     href: "https://{{.preferred_username}}.cloud.ocis.test"
+     title: 
+       "en": "oCIS Instance for Marie"
+       "de": "oCIS Instanz für Marie"
+     break: false
+  -  claim: "email"
+     regex: .+@example\.org
+     href: "https://example-org.cloud.ocis.test"
+     title:
+       "en": "oCIS Instance for example.org"
+       "de": "oCIS Instanz für example.org"
+     break: true
+  -  claim: "email"
+     regex: .+@example\.com
+     href: "https://example-com.cloud.ocis.test"
+     title:
+       "en": "oCIS Instance for example.com"
+       "de": "oCIS Instanz für example.com"
+     break: true
+  -  claim: "email"
+     regex: .+@.+\..+
+     href: "https://cloud.ocis.test"
+     title:
+       "en": "oCIS Instance"
+       "de": "oCIS Instanz"
+     break: true
+----
+
+Now, an authenticated webfinger request for `acct:[email protected]` (when logged in as _marie_) would return two instances, based on her `email` claim, the regex matches and break flags:
+
+[source,json]
+----
+{
+    "subject": "acct:[email protected]",
+    "links": [
+        {
+            "rel": "http://openid.net/specs/connect/1.0/issuer",
+            "href": "https://sso.example.org/cas/oidc/"
+        },
+        {
+            "rel": "http://webfinger.owncloud/rel/server-instance",
+            "href": "https://marie.cloud.ocis.test",
+            "titles": {
+                "en": "oCIS Instance for Marie",
+                "de": "oCIS Instanz für Marie"
+            }
+        },
+        {
+            "rel": "http://webfinger.owncloud/rel/server-instance",
+            "href": "https://xyz.drive.example.org",
+            "titles": {
+                "en": "oCIS Instance for example.org",
+                "de": "oCIS Instanz für example.org"
+            }
+        }
+    ]
+}
+----
+
+== Configuration
+
+include::partial$deployment/services/env-and-yaml.adoc[]

modules/ROOT/partials/nav.adoc

@@ -54,6 +54,7 @@
 **** xref:deployment/services/s-list/users.adoc[Users]
 **** xref:deployment/services/s-list/web.adoc[Web]
 **** xref:deployment/services/s-list/webdav.adoc[WebDAV]
+**** xref:deployment/services/s-list/webfinger.adoc[Webfinger]
 * Maintenance
 ** Backup and Restore
 *** xref:maintenance/b-r/backup.adoc[Backup]