Webfinger Service Configuration

Table of Contents

Introduction
OpenID Connect Discovery
Authenticated Instance Discovery
Configure Different Instances Based on OpenID Connect UserInfo Claims
Configuration
- Environment Variables
- YAML Example

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.

master + Rolling 6.6.1

Environment variables for the webfinger service
Name	IV	Type	Default Value	Description
`OCIS_TRACING_ENABLED` `WEBFINGER_TRACING_ENABLED`	pre5.0	bool	false	Activates tracing.
`OCIS_TRACING_TYPE` `WEBFINGER_TRACING_TYPE`	pre5.0	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`	pre5.0	string		The endpoint of the tracing agent.
`OCIS_TRACING_COLLECTOR` `WEBFINGER_TRACING_COLLECTOR`	pre5.0	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`	pre5.0	string		The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'.
`OCIS_LOG_PRETTY` `WEBFINGER_LOG_PRETTY`	pre5.0	bool	false	Activates pretty log output.
`OCIS_LOG_COLOR` `WEBFINGER_LOG_COLOR`	pre5.0	bool	false	Activates colorized log output.
`OCIS_LOG_FILE` `WEBFINGER_LOG_FILE`	pre5.0	string		The path to the log file. Activates logging to this file if set.
`WEBFINGER_DEBUG_ADDR`	pre5.0	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`	pre5.0	string		Token to secure the metrics endpoint.
`WEBFINGER_DEBUG_PPROF`	pre5.0	bool	false	Enables pprof, which can be used for profiling.
`WEBFINGER_DEBUG_ZPAGES`	pre5.0	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
`WEBFINGER_HTTP_ADDR`	pre5.0	string	127.0.0.1:9275	The bind address of the HTTP service.
`WEBFINGER_HTTP_ROOT`	pre5.0	string	/	Subdirectory that serves as the root for this HTTP service.
`OCIS_CORS_ALLOW_ORIGINS` `WEBFINGER_CORS_ALLOW_ORIGINS`	pre5.0	[]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`	pre5.0	[]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`	pre5.0	[]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`	pre5.0	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`	pre5.0	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`	pre5.0	string		Path/File name of the TLS server certificate (in PEM format) for the http services.
`OCIS_HTTP_TLS_KEY`	pre5.0	string		Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services.
`WEBFINGER_RELATIONS`	pre5.0	[]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`	pre5.0	string	https://localhost:9200	The identity provider href for the openid-discovery relation.
`OCIS_URL` `WEBFINGER_OWNCLOUD_SERVER_INSTANCE_URL`	pre5.0	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`	pre5.0	bool	false	Allow insecure connections to the WEBFINGER service.

YAML Example

Note the file shown below must be renamed and placed in the correct folder according to the Configuration File Naming conventions to be effective.
See the Notes for Environment Variables if you want to use environment variables in the yaml file.

master + Rolling 6.6.1

# 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