Webfinger Service Configuration

Introduction

The Infinite Scale webfinger service provides an RFC7033 WebFinger lookup of ownCloud instances relevant for a given user account. 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:

{
    "subject": "acct:einstein@drive.ocis.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 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:

{
    "subject": "acct:einstein@drive.ocis.test",
    "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 OpenID Connect UserInfo Claims

A more complex example for configuring different instances could look like this:

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:me@example.org (when logged in as marie) would return two instances, based on her email claim, the regex matches and break flags:

{
    "subject": "acct:marie@example.org",
    "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

Environment Variables

The webfinger service is configured via the following environment variables. Read the Environment Variable Types documentation for important details. Column IV shows with which release the environment variable has been introduced.

404: Not Found

  • 8.1.0

404: Not Found

YAML Example

  • 8.1.0

404: Not Found