Webfinger

Abstract

The webfinger service provides an RFC7033 WebFinger lookup of ownCloud instances relevant for a given user account via endpoints a the /.well-known/webfinger implementation.

It is based on https://github.com/owncloud/lookup-webfinger-sciebo but also returns localized titles in addition to the href property.

OpenID Connect Discovery
Authenticated Instance Discovery
Configure Different Instances Based on OpenidConnect UserInfo Claims
Example Yaml Config

OpenID Connect Discovery

Clients can make an unauthenticated GET https://drive.ocis.test/.well-known/webfinger?resource=https%3A%2F%2Fdrive.ocis.test request to discover the OpenID Connect Issuer in the http://openid.net/specs/connect/1.0/issuer relation:

{
    "subject": "https://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 OpenidConnect 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"
            }
        }
    ]
}

Example Yaml Config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


# Autogenerated
# Filename: webfinger-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:0
  token: ""
  pprof: false
  zpages: false
http:
  addr: 127.0.0.1:0
  root: /
  cors:
    allow_origins:
    - https://localhost:9200
    allow_methods: []
    allow_headers: []
    allow_credentials: false
  tls:
    enabled: false
    cert: ""
    key: ""
instances:
- claim: sub
  regex: .+
  href: '{{.OCIS_URL}}'
  titles:
    en: oCIS Instance
  break: false
relations:
- http://openid.net/specs/connect/1.0/issuer
- http://webfinger.owncloud/rel/server-instance
idp: https://localhost:9200
ocis_url: https://localhost:9200
insecure: false

Environment Variables

Name	Type	Default Value	Description
OCIS_TRACING_ENABLED WEBFINGER_TRACING_ENABLED	bool	false	Activates tracing.
OCIS_TRACING_TYPE WEBFINGER_TRACING_TYPE	string		The type of tracing. Defaults to ‘’, which is the same as ‘jaeger’. Allowed tracing types are ‘jaeger’ and ’’ as of now.
OCIS_TRACING_ENDPOINT WEBFINGER_TRACING_ENDPOINT	string		The endpoint of the tracing agent.
OCIS_TRACING_COLLECTOR WEBFINGER_TRACING_COLLECTOR	string		The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.
OCIS_LOG_LEVEL WEBFINGER_LOG_LEVEL	string		The log level. Valid values are: ‘panic’, ‘fatal’, ’error’, ‘warn’, ‘info’, ‘debug’, ’trace’.
OCIS_LOG_PRETTY WEBFINGER_LOG_PRETTY	bool	false	Activates pretty log output.
OCIS_LOG_COLOR WEBFINGER_LOG_COLOR	bool	false	Activates colorized log output.
OCIS_LOG_FILE WEBFINGER_LOG_FILE	string		The path to the log file. Activates logging to this file if set.
WEBFINGER_DEBUG_ADDR	string	127.0.0.1:0	Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.
WEBFINGER_DEBUG_TOKEN	string		Token to secure the metrics endpoint.
WEBFINGER_DEBUG_PPROF	bool	false	Enables pprof, which can be used for profiling.
WEBFINGER_DEBUG_ZPAGES	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
WEBFINGER_HTTP_ADDR	string	127.0.0.1:0	The bind address of the HTTP service.
WEBFINGER_HTTP_ROOT	string	/	Subdirectory that serves as the root for this HTTP service.
OCIS_CORS_ALLOW_ORIGINS WEBFINGER_CORS_ALLOW_ORIGINS	[]string	[https://localhost:9200]	A list of allowed CORS origins. See following chapter for more details: Access-Control-Allow-Origin at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_METHODS WEBFINGER_CORS_ALLOW_METHODS	[]string	[]	A list of allowed CORS methods. See following chapter for more details: Access-Control-Request-Method at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_HEADERS WEBFINGER_CORS_ALLOW_HEADERS	[]string	[]	A list of allowed CORS headers. See following chapter for more details: Access-Control-Request-Headers at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_CREDENTIALS WEBFINGER_CORS_ALLOW_CREDENTIALS	bool	false	Allow credentials for CORS.See following chapter for more details: Access-Control-Allow-Credentials at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials.
OCIS_HTTP_TLS_ENABLED	bool	false	Activates TLS for the http based services using the server certifcate and key configured via OCIS_HTTP_TLS_CERTIFICATE and OCIS_HTTP_TLS_KEY. If OCIS_HTTP_TLS_CERTIFICATE is not set a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true.
OCIS_HTTP_TLS_CERTIFICATE	string		Path/File name of the TLS server certificate (in PEM format) for the http services.
OCIS_HTTP_TLS_KEY	string		Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services.
WEBFINGER_RELATIONS	[]string	[http://openid.net/specs/connect/1.0/issuer http://webfinger.owncloud/rel/server-instance]	A list of relation URIs or registered relation types to add to webfinger responses. See the Environment Variable Types description for more details.
OCIS_URL OCIS_OIDC_ISSUER WEBFINGER_OIDC_ISSUER	string	https://localhost:9200	The identity provider href for the openid-discovery relation.
OCIS_URL WEBFINGER_OWNCLOUD_SERVER_INSTANCE_URL	string	https://localhost:9200	The URL for the legacy ownCloud server instance relation (not to be confused with the product ownCloud Server). It defaults to the OCIS_URL but can be overridden to support some reverse proxy corner cases. To shard the deployment, multiple instances can be configured in the configuration file.
OCIS_INSECURE WEBFINGER_INSECURE	bool	false	Allow insecure connections to the WEBFINGER service.