mirror of
https://github.com/strukturag/nextcloud-spreed-signaling
synced 2024-05-19 14:06:32 +02:00
Document hello version 2.0 authentication.
This commit is contained in:
parent
9c159dc4f8
commit
0338e9db42
|
@ -140,7 +140,7 @@ Message format (Client -> Server):
|
||||||
"id": "unique-request-id",
|
"id": "unique-request-id",
|
||||||
"type": "hello",
|
"type": "hello",
|
||||||
"hello": {
|
"hello": {
|
||||||
"version": "the-protocol-version-must-be-1.0",
|
"version": "the-protocol-version",
|
||||||
"auth": {
|
"auth": {
|
||||||
"url": "the-url-to-the-auth-backend",
|
"url": "the-url-to-the-auth-backend",
|
||||||
"params": {
|
"params": {
|
||||||
|
@ -159,7 +159,7 @@ Message format (Server -> Client):
|
||||||
"sessionid": "the-unique-session-id",
|
"sessionid": "the-unique-session-id",
|
||||||
"resumeid": "the-unique-resume-id",
|
"resumeid": "the-unique-resume-id",
|
||||||
"userid": "the-user-id-for-known-users",
|
"userid": "the-user-id-for-known-users",
|
||||||
"version": "the-protocol-version-must-be-1.0",
|
"version": "the-protocol-version",
|
||||||
"server": {
|
"server": {
|
||||||
"features": ["optional", "list, "of", "feature", "ids"],
|
"features": ["optional", "list, "of", "feature", "ids"],
|
||||||
...additional information about the server...
|
...additional information about the server...
|
||||||
|
@ -172,12 +172,82 @@ future version. Clients should use the data from the
|
||||||
[`welcome` message](#welcome-message) instead.
|
[`welcome` message](#welcome-message) instead.
|
||||||
|
|
||||||
|
|
||||||
|
### Protocol version "1.0"
|
||||||
|
|
||||||
|
For protocol version `1.0` in the `hello` request, the `params` from the `auth`
|
||||||
|
field are sent to the Nextcloud backend for [validation](#backend-validation).
|
||||||
|
|
||||||
|
|
||||||
|
### Protocol version "2.0"
|
||||||
|
|
||||||
|
For protocol version `2.0` in the `hello` request, the `params` from the `auth`
|
||||||
|
field must contain a `token` entry containing a [JWT](https://jwt.io/).
|
||||||
|
|
||||||
|
The JWT must contain the following fields:
|
||||||
|
- `iss`: URL of the Nextcloud server that issued the token.
|
||||||
|
- `iat`: Timestamp when the token has been issued.
|
||||||
|
- `exp`: Timestamp of the token expiration.
|
||||||
|
- `sub`: User Id (if known).
|
||||||
|
- `userdata`: Optional JSON containing more user data.
|
||||||
|
|
||||||
|
It must be signed with an RSA, ECDSA or Ed25519 key.
|
||||||
|
|
||||||
|
Example token:
|
||||||
|
```
|
||||||
|
eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJodHRwczovL25leHRjbG91ZC1tYXN0ZXIubG9jYWwvIiwiaWF0IjoxNjU0ODQyMDgwLCJleHAiOjE2NTQ4NDIzODAsInN1YiI6ImFkbWluIiwidXNlcmRhdGEiOnsiZGlzcGxheW5hbWUiOiJBZG1pbmlzdHJhdG9yIn19.5rV0jh89_0fG2L-BUPtciu1q49PoYkLboj33EOdD0qQeYcvE7_di2r5WXM1WmKUCOGeX3hzn6qldDMrJBNuxvQ
|
||||||
|
```
|
||||||
|
|
||||||
|
Example public key:
|
||||||
|
```
|
||||||
|
-----BEGIN PUBLIC KEY-----
|
||||||
|
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEIoCsNSCXyxK25zvSKRio0uiBzwub
|
||||||
|
ONq3tiGTPZo3p2Ogn6wAhhsuSxbFuUQDWMX7Tsu9fDzVdwpRHPT4y3V9cA==
|
||||||
|
-----END PUBLIC KEY-----
|
||||||
|
```
|
||||||
|
|
||||||
|
Example payload:
|
||||||
|
```
|
||||||
|
{
|
||||||
|
"iss": "https://nextcloud-master.local/",
|
||||||
|
"iat": 1654842080,
|
||||||
|
"exp": 1654842380,
|
||||||
|
"sub": "admin",
|
||||||
|
"userdata": {
|
||||||
|
"displayname": "Administrator"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The public key is retrieved from the capabilities of the Nextcloud instance
|
||||||
|
in `config` key `hello-v2-token-key` inside `signaling`.
|
||||||
|
|
||||||
|
```
|
||||||
|
"spreed": {
|
||||||
|
"features": [
|
||||||
|
"audio",
|
||||||
|
"video",
|
||||||
|
"chat-v2",
|
||||||
|
"conversation-v4",
|
||||||
|
...
|
||||||
|
],
|
||||||
|
"config": {
|
||||||
|
…
|
||||||
|
"signaling": {
|
||||||
|
"hello-v2-token-key": "-----BEGIN RSA PUBLIC KEY----- ..."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
### Backend validation
|
### Backend validation
|
||||||
|
|
||||||
The server validates the connection request against the passed auth backend
|
For `hello` protocol version `1.0`, the server validates the connection request
|
||||||
(needs to make sure the passed url / hostname is in a whitelist). It performs
|
against the passed auth backend (needs to make sure the passed url / hostname
|
||||||
a POST request and passes the provided `params` as JSON payload in the body
|
is in a whitelist).
|
||||||
of the request.
|
|
||||||
|
It performs a POST request and passes the provided `params` as JSON payload in
|
||||||
|
the body of the request.
|
||||||
|
|
||||||
Message format (Server -> Auth backend):
|
Message format (Server -> Auth backend):
|
||||||
|
|
||||||
|
@ -236,7 +306,7 @@ Message format (Client -> Server):
|
||||||
"id": "unique-request-id",
|
"id": "unique-request-id",
|
||||||
"type": "hello",
|
"type": "hello",
|
||||||
"hello": {
|
"hello": {
|
||||||
"version": "the-protocol-version-must-be-1.0",
|
"version": "the-protocol-version",
|
||||||
"auth": {
|
"auth": {
|
||||||
"type": "the-client-type",
|
"type": "the-client-type",
|
||||||
...other attributes depending on the client type...
|
...other attributes depending on the client type...
|
||||||
|
@ -294,7 +364,7 @@ Message format (Client -> Server):
|
||||||
"id": "unique-request-id",
|
"id": "unique-request-id",
|
||||||
"type": "hello",
|
"type": "hello",
|
||||||
"hello": {
|
"hello": {
|
||||||
"version": "the-protocol-version-must-be-1.0",
|
"version": "the-protocol-version",
|
||||||
"resumeid": "the-resume-id-from-the-original-hello-response"
|
"resumeid": "the-resume-id-from-the-original-hello-response"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -306,7 +376,7 @@ Message format (Server -> Client):
|
||||||
"type": "hello",
|
"type": "hello",
|
||||||
"hello": {
|
"hello": {
|
||||||
"sessionid": "the-unique-session-id",
|
"sessionid": "the-unique-session-id",
|
||||||
"version": "the-protocol-version-must-be-1.0"
|
"version": "the-protocol-version"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue