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.
Name | IV | Type | Default Value | Description |
---|---|---|---|---|
|
pre5.0 |
bool |
false |
Activates tracing. |
|
pre5.0 |
string |
|
The type of tracing. Defaults to '', which is the same as 'jaeger'. Allowed tracing types are 'jaeger' and '' as of now. |
|
pre5.0 |
string |
|
The endpoint of the tracing agent. |
|
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. |
|
pre5.0 |
string |
|
The log level. Valid values are: 'panic', 'fatal', 'error', 'warn', 'info', 'debug', 'trace'. |
|
pre5.0 |
bool |
false |
Activates pretty log output. |
|
pre5.0 |
bool |
false |
Activates colorized log output. |
|
pre5.0 |
string |
|
The path to the log file. Activates logging to this file if set. |
|
pre5.0 |
string |
127.0.0.1:0 |
Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed. |
|
pre5.0 |
string |
|
Token to secure the metrics endpoint. |
|
pre5.0 |
bool |
false |
Enables pprof, which can be used for profiling. |
|
pre5.0 |
bool |
false |
Enables zpages, which can be used for collecting and viewing in-memory traces. |
|
pre5.0 |
string |
127.0.0.1:0 |
The bind address of the HTTP service. |
|
pre5.0 |
string |
/ |
Subdirectory that serves as the root for this HTTP service. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
pre5.0 |
string |
|
Path/File name of the TLS server certificate (in PEM format) for the http services. |
|
pre5.0 |
string |
|
Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services. |
|
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. |
|
pre5.0 |
string |
https://localhost:9200 |
The identity provider href for the openid-discovery relation. |
|
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. |
|
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.
# 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