mirror of
https://github.com/opencloud-eu/opencloud.git
synced 2026-01-05 19:59:37 -06:00
107 lines
5.2 KiB
Markdown
107 lines
5.2 KiB
Markdown
---
|
|
title: "Storage Registry Discovery"
|
|
date: 2021-05-04T14:01:00+01:00
|
|
weight: 40
|
|
geekdocRepo: https://github.com/owncloud/ocis
|
|
geekdocEditPath: edit/master/docs/ocis
|
|
geekdocFilePath: storage_registry_discovery.md
|
|
---
|
|
|
|
## Introduction
|
|
|
|
In order for an oCIS client to access oCIS storage spaces for an End-User, the client needs to know where the oCIS instance is. oCIS uses WebFinger [RFC7033](http://tools.ietf.org/html/rfc7033) to locate the oCIS instance for an End-User.
|
|
|
|
This discovery is optional. If the client has another way of discovering the OpenID instance, e.g. when logging in with a username a static domain might be configured or the domain in the URL might be used.
|
|
|
|
For guest accounts that do not have an OIDC issuer or whose IdP is not part of a trusted federation clients may fall back to a local IdP.
|
|
|
|
## User Input using E-Mail Address Syntax
|
|
|
|
To find the oCIS instance for the given user input in the form of an e-mail address `joe@example.com`, the WebFinger parameters are as follows:
|
|
|
|
| WebFinger Parameter | Value |
|
|
|-|-|
|
|
| `resource` | `acct:joe@example.com` |
|
|
| `host` | `example.com` |
|
|
| `rel` | http://owncloud.com/specs/ocis/1.0/instance |
|
|
|
|
Note that in this case, [the `acct:` scheme](http://tools.ietf.org/html/draft-ietf-appsawg-acct-uri-07) is prepended to the identifier.
|
|
|
|
The client (relying party) would make the following WebFinger request to discover the oCIS instance location (with line wraps within lines for display purposes only):
|
|
|
|
```
|
|
GET /.well-known/webfinger
|
|
?resource=acct%3Ajoe%40example.com
|
|
&rel=http%3A%2F%2Fowncloud.com%2Fspecs%2Focis%2F1.0%2Finstance
|
|
HTTP/1.1
|
|
Host: example.com
|
|
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/jrd+json
|
|
|
|
{
|
|
"subject": "acct:joe@example.com",
|
|
"links":
|
|
[
|
|
{
|
|
"rel": "http://owncloud.com/specs/ocis/1.0/instance",
|
|
"href": "https://cloud.example.com"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
{{< hint >}}
|
|
Note: the `example.com` domain is derived from the email.
|
|
{{< /hint >}}
|
|
|
|
{{< hint danger >}}
|
|
The `https://cloud.example.com` domain above would point to the ocis instance.
|
|
TODO that ins ocis web ... not the registry ... hmmmm
|
|
maybe introduce an ocis provider which then has an `/.well-known/ocis-configuration`, similar to `/.well-known/openid-configuration`?
|
|
It would contain
|
|
- the ocis domain, e.g. `https://cloud.example.com`
|
|
- the web endpoint, e.g. `https://cloud.example.com`
|
|
- the registry / drives endpoint, e.g. `https://cloud.example.com/graph/v0.1/drives/me` see [Add draft of adr for spaces API. #1827](https://github.com/owncloud/ocis/pull/1827)
|
|
|
|
|
|
example:
|
|
```
|
|
HTTP/1.1 200 OK
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"instance": "https://cloud.example.com",
|
|
"graph_endpoint": "https://cloud.example.com/graph/v0.0",
|
|
"ocis_web_config": "https://cloud.example.com/web/config.json",
|
|
"issuer": "https://idp.example.com",
|
|
}
|
|
```
|
|
|
|
`graph_endpoint` is the open-graph-api endpoint that is used to list storage spaces at e.g. `https://cloud.example.com/graph/v0.1/me/drives`.
|
|
|
|
`ocis_web_config` points ocis web to the config for the instance. Maybe we can add more config in the `/.well-known/ocis-configuration` to replace the config.json? Is this the new status.php? How safe is it to expose all this info ...?
|
|
|
|
The `issuer` could be used to detect the issuer that is used if no other issuer is found ... might be a fallback_issuer, but actually we may decide to skid the OIDC discovery and rely on this property. Maybe we need it if no IdP is present yet or the `/.well-known/openid-configuration` is not set up / reachable.
|
|
|
|
|
|
{{< /hint >}}
|
|
|
|
## Obtaining oCIS Provider Configuration Information
|
|
Using the `instance` location discovered as described above or by other means, the oCIS Provider's configuration information can be retrieved.
|
|
|
|
oCIS Providers supporting Discovery MUST make a JSON document available at the path formed by concatenating the string `/.well-known/openid-configuration` to the `instance`. The syntax and semantics of `.well-known` are defined in [RFC5785](http://tools.ietf.org/html/rfc5785) and apply to the `instance` value when it contains no path component. `ocis-configuration` MUST point to a JSON document compliant with this specification and MUST be returned using the `application/json` content type.
|
|
|
|
### oCIS Provider Configuration Request
|
|
|
|
An oCIS Provider Configuration Document MUST be queried using an HTTP GET request at the previously specified path.
|
|
|
|
The client (relying party) would make the following request to the instance https://example.com to obtain its Configuration information, since the Issuer contains no path component:
|
|
|
|
GET /.well-known/openid-configuration HTTP/1.1
|
|
Host: example.com
|
|
If the Issuer value contains a path component, any terminating / MUST be removed before appending /.well-known/openid-configuration. The RP would make the following request to the Issuer https://example.com/issuer1 to obtain its Configuration information, since the Issuer contains a path component:
|
|
|
|
GET /issuer1/.well-known/openid-configuration HTTP/1.1
|
|
Host: example.com
|
|
Using path components enables supporting multiple issuers per host. This is required in some multi-tenant hosting configurations. This use of .well-known is for supporting multiple issuers per host; unlike its use in RFC 5785 [RFC5785], it does not provide general information about the host. |