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.

  • master

Environment variables for the webfinger service
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

[*]

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.

YAML Example

  • master

# 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:
    - '*'
    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