ownCloud
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage
  1. ownCloud
  2. /
  3. Services
  4. /
  5. Webfinger
Edit page

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.

Table of Contents

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:9279
  token: ""
  pprof: false
  zpages: false
http:
  addr: 127.0.0.1:9275
  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:9279 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:9275 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.
gdoc_arrow_left_alt Service Configuration Service Configuration gdoc_arrow_right_alt