cqrenet/mxids
3
0
Fork 0
Code Pull Requests 10 Actions Releases Activity

Prepare REST backend for directory flow

Browse Source
This commit is contained in:
Maxime Dor
2017-10-01 02:20:15 +02:00
parent 8d0b0edad2
commit 786e4a8f91
3 changed files with 80 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/backends/rest.md
View File

@@ -6,33 +6,33 @@ The REST backend allows you to query identity data in existing webapps, like:
- self-hosted clouds (Nextcloud, ownCloud, ...)
It supports the following mxisd flows:
- Identity lookup
- Authentication
- [Authentication](#authentication)
- [Directory](#directory)
- [Identity](#identity)
To integrate this backend with your webapp, you will need to implement three specific REST endpoints detailed below.
## Configuration
| Key | Default | Description |
---------------------------------|---------------------------------------|------------------------------------------------------|
| rest.enabled | false | Globally enable/disable the REST backend |
| rest.host | *empty* | Default base URL to use for the different endpoints. |
| rest.endpoints.auth | /_mxisd/identity/api/v1/auth | Endpoint to validate credentials |
| rest.endpoints.identity.single | /_mxisd/identity/api/v1/lookup/single | Endpoint to query a single 3PID |
| rest.endpoints.identity.bulk | /_mxisd/identity/api/v1/lookup/bulk | Endpoint to query a list of 3PID |
| Key | Default | Description |
---------------------------------|----------------------------------------------|------------------------------------------------------|
| rest.enabled | false | Globally enable/disable the REST backend |
| rest.host | *empty* | Default base URL to use for the different endpoints. |
| rest.endpoints.auth | /_mxisd/backend/api/v1/auth/login | Validate credentials and get user profile |
| rest.endpoints.directory | /_mxisd/backend/api/v1/directory/user/search | Search for users by arbitrary input |
| rest.endpoints.identity.single | /_mxisd/backend/api/v1/identity/single | Endpoint to query a single 3PID |
| rest.endpoints.identity.bulk | /_mxisd/backend/api/v1/identity/bulk | Endpoint to query a list of 3PID |
Endpoint values can handle two formats:
- URL Path starting with `/` that gets happened to the `rest.host`
- Full URL, if you want each endpoint to go to a specific server/protocol/port
`rest.host` is only mandatory if at least one endpoint is not a full URL.
`rest.host` is mandatory if at least one endpoint is not a full URL.
## Endpoints
### Authenticate
Configured with `rest.endpoints.auth`
### Authentication
HTTP method: `POST`
Encoding: JSON UTF-8
Content-type: JSON UTF-8
#### Request Body
```
@@ -84,12 +84,47 @@ If the authentication succeed:
}
```
### Lookup
#### Single
Configured with `rest.endpoints.identity.single`
### Directory
HTTP method: `POST`
Content-type: JSON UTF-8
#### Request Body
```
{
"search_term": "doe"
}
```
#### Response Body:
If users found:
```
{
"limited": false,
"results": [
{
"display_name": "John Doe",
"avatar_url": "http://domain.tld/path/to/avatar.png",
"user_id": "UserIdLocalpart"
},
{
...
}
]
}
```
If no user found:
```
{
"limited": false,
"results": []
}
```
### Identity
#### Single 3PID lookup
HTTP method: `POST`
Encoding: JSON UTF-8
Content-type: JSON UTF-8
#### Request Body
```
@@ -122,11 +157,9 @@ If no match was found:
{}
```
#### Bulk
Configured with `rest.endpoints.identity.bulk`
#### Bulk 3PID lookup
HTTP method: `POST`
Encoding: JSON UTF-8
Content-type: JSON UTF-8
#### Request Body
```
@@ -175,4 +208,4 @@ If no match was found:
{
"lookup": []
}
```
```

29
src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java
View File

@@ -60,16 +60,9 @@ public class RestBackendConfig {
public static class Endpoints {
private IdentityEndpoints identity = new IdentityEndpoints();
private String auth;
public IdentityEndpoints getIdentity() {
return identity;
}
public void setIdentity(IdentityEndpoints identity) {
this.identity = identity;
}
private String directory;
private IdentityEndpoints identity = new IdentityEndpoints();
public String getAuth() {
return auth;
@@ -79,6 +72,22 @@ public class RestBackendConfig {
this.auth = auth;
}
public String getDirectory() {
return directory;
}
public void setDirectory(String directory) {
this.directory = directory;
}
public IdentityEndpoints getIdentity() {
return identity;
}
public void setIdentity(IdentityEndpoints identity) {
this.identity = identity;
}
}
private Logger log = LoggerFactory.getLogger(RestBackendConfig.class);
@@ -136,11 +145,13 @@ public class RestBackendConfig {
if (isEnabled()) {
endpoints.setAuth(buildEndpointUrl(endpoints.getAuth()));
endpoints.setDirectory(buildEndpointUrl(endpoints.getDirectory()));
endpoints.identity.setSingle(buildEndpointUrl(endpoints.identity.getSingle()));
endpoints.identity.setBulk(buildEndpointUrl(endpoints.identity.getBulk()));
log.info("Host: {}", getHost());
log.info("Auth endpoint: {}", endpoints.getAuth());
log.info("Directory endpoint: {}", endpoints.getDirectory());
log.info("Identity Single endpoint: {}", endpoints.identity.getSingle());
log.info("Identity Bulk endpoint: {}", endpoints.identity.getBulk());
}

7
src/main/resources/application.yaml
View File

@@ -37,10 +37,11 @@ lookup:
rest:
endpoints:
auth: "/_mxisd/identity/api/v1/auth"
auth: '/_mxisd/backend/api/v1/auth/login'
directory: '/_mxisd/backend/api/v1/directory/user/search'
identity:
single: "/_mxisd/identity/api/v1/lookup/single"
bulk: "/_mxisd/identity/api/v1/lookup/bulk"
single: '/_mxisd/backend/api/v1/identity/lookup/single'
bulk: '/_mxisd/backend/api/v1/identity/lookup/bulk'
ldap:
enabled: false