tomas.kracmar/ma1sd
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve docs

Browse Source
This commit is contained in:
Max Dor
2019-02-06 03:53:42 +01:00
parent 5c660fdcaf
commit 67bc18af7d
10 changed files with 77 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
README.md
View File

@@ -14,7 +14,7 @@ mxisd - Federated Matrix Identity Server
# Overview # Overview
mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures with [enhanced features](#features). mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures with [enhanced features](#features).
As an enhanced Identity service, it implements the [Matrix Identity service API](https://kamax.io/matrix/api/identity_service/unstable.html) As an enhanced Identity service, it implements the [Identity service API](https://matrix.org/docs/spec/identity_service/r0.1.0.html)
and several [extra features](#features) that greatly enhance user experience within Matrix. and several [extra features](#features) that greatly enhance user experience within Matrix.
It is the one stop shop for anything regarding Authentication, Directory and Identity management in Matrix built in a It is the one stop shop for anything regarding Authentication, Directory and Identity management in Matrix built in a
single coherent product. single coherent product.
@@ -33,15 +33,15 @@ users. 3PIDs can be anything that uniquely and globally identify a user, like:
If you are unfamiliar with the Identity vocabulary and concepts in Matrix, **please read this [introduction](docs/concepts.md)**. If you are unfamiliar with the Identity vocabulary and concepts in Matrix, **please read this [introduction](docs/concepts.md)**.
# Features # Features
[Identity](docs/features/identity.md): As a [regular Matrix Identity service](https://kamax.io/matrix/api/identity_service/unstable.html#general-principles): [Identity](docs/features/identity.md): As a [regular Matrix Identity service](https://matrix.org/docs/spec/identity_service/r0.1.0.html#general-principles):
- Search for people by 3PID using its own Identity stores - Search for people by 3PID using its own Identity stores
([Spec](https://kamax.io/matrix/api/identity_service/unstable.html#association-lookup)) ([Spec](https://matrix.org/docs/spec/identity_service/r0.1.0.html#association-lookup))
- Invite people to rooms by 3PID using its own Identity stores, with notifications to the invitee (Email, SMS, etc.) - Invite people to rooms by 3PID using its own Identity stores, with notifications to the invitee (Email, SMS, etc.)
([Spec](https://kamax.io/matrix/api/identity_service/unstable.html#post-matrix-identity-api-v1-store-invite)) ([Spec](https://matrix.org/docs/spec/identity_service/r0.1.0.html#post-matrix-identity-api-v1-store-invite))
- Allow users to add 3PIDs to their settings/profile - Allow users to add 3PIDs to their settings/profile
([Spec](https://kamax.io/matrix/api/identity_service/unstable.html#establishing-associations)) ([Spec](https://matrix.org/docs/spec/identity_service/r0.1.0.html#establishing-associations))
- Register accounts on your Homeserver with 3PIDs - Register accounts on your Homeserver with 3PIDs
([Spec](https://kamax.io/matrix/api/identity_service/unstable.html#establishing-associations)) ([Spec](https://matrix.org/docs/spec/identity_service/r0.1.0.html#establishing-associations))
As an enhanced Identity service: As an enhanced Identity service:
- [Federation](docs/features/federation.md): Use a recursive lookup mechanism when searching and inviting people by 3PID, - [Federation](docs/features/federation.md): Use a recursive lookup mechanism when searching and inviting people by 3PID,

22
docs/faq.md
View File

@@ -16,6 +16,18 @@ of the Matrix protocol is required for some advanced features.
If all fails, come over to [the project room](https://matrix.to/#/#mxisd:kamax.io) and we'll do our best to get you If all fails, come over to [the project room](https://matrix.to/#/#mxisd:kamax.io) and we'll do our best to get you
started and answer questions you might have. started and answer questions you might have.
### What kind of setup is mxisd really designed for?
mxisd is primarily designed for setups that:
- Care for their privacy
- Have their own domains
- Use that domain for their email addresses and all other services
- Already have an Identity store, typically LDAP-based.
If you meet all the conditions, then you are the prime use case we designed mxisd for.
If you meet some of the conditions, but not all, mxisd will still be a good fit for you but you won't fully enjoy all its
features.
### Do I need to use mxisd if I run a Homeserver? ### Do I need to use mxisd if I run a Homeserver?
No, but it is strongly recommended, even if you don't use any Identity store or integration. No, but it is strongly recommended, even if you don't use any Identity store or integration.
@@ -23,9 +35,6 @@ In its default configuration, mxisd uses other federated public servers when per
It can also [be configured](features/identity.md#lookups) to use the central matrix.org servers, giving you access to at It can also [be configured](features/identity.md#lookups) to use the central matrix.org servers, giving you access to at
least the same information as if you were not running it. least the same information as if you were not running it.
It will also give your users a choice to make their 3PIDs available publicly, ensuring they are made aware of the
privacy consequences, which is not the case with the central Matrix.org servers.
So mxisd is like your gatekeeper and guardian angel. It does not change what you already know, just adds some nice So mxisd is like your gatekeeper and guardian angel. It does not change what you already know, just adds some nice
simple features on top of it. simple features on top of it.
@@ -47,13 +56,14 @@ Accounts cannot currently migrate/move from one server to another.
See a [brief explanation document](concepts.md) about Matrix and mxisd concepts and vocabulary. See a [brief explanation document](concepts.md) about Matrix and mxisd concepts and vocabulary.
### I already use the synapse LDAP3 auth provider. Why should I care about mxisd? ### I already use the synapse LDAP3 auth provider. Why should I care about mxisd?
The [synapse LDAP3 auth provider](https://github.com/matrix-org/matrix-synapse-ldap3) is not longer maintained and The [synapse LDAP3 auth provider](https://github.com/matrix-org/matrix-synapse-ldap3) is not longer maintained despite
only handles on specific flow: validate credentials at login. saying so and only handles on specific flow: validate credentials at login.
It does not: It does not:
- Auto-provision user profiles - Auto-provision user profiles
- Integrate with Identity management - Integrate with Identity management
- Integrate with Directory searches - Integrate with Directory searches
- Integrate with Profile data
mxisd is a replacement and enhancement of it, offering coherent results in all areas, which the LDAP3 auth provider mxisd is a replacement and enhancement of it, offering coherent results in all areas, which the LDAP3 auth provider
does not. does not.
@@ -74,7 +84,7 @@ No.
In its default configuration, mxisd does not talk to the central Identity server matrix.org to avoid leaking your private In its default configuration, mxisd does not talk to the central Identity server matrix.org to avoid leaking your private
data and those of people you might know. data and those of people you might know.
mxisd [can be configured](features/identity.md#lookups) to talk to the central Identity servers if you wish. [You can configure it](features/identity.md#lookups) to talk to the central Identity servers if you wish.
### So mxisd is just a big hack! I don't want to use non-official features! ### So mxisd is just a big hack! I don't want to use non-official features!
mxisd primary concerns are your privacy and to always be compatible with the Matrix ecosystem and the Identity service API. mxisd primary concerns are your privacy and to always be compatible with the Matrix ecosystem and the Identity service API.

2
docs/features/identity.md
View File

@@ -1,7 +1,7 @@
# Identity # Identity
**WARNING**: This document is incomplete and can be misleading. **WARNING**: This document is incomplete and can be misleading.
Implementation of the [Unofficial Matrix Identity Service API](https://kamax.io/matrix/api/identity_service/unstable.html). Implementation of the [Identity Service API r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html).
## Lookups ## Lookups
If you would like to use the central matrix.org Identity server to ensure maximum discovery at the cost of potentially If you would like to use the central matrix.org Identity server to ensure maximum discovery at the cost of potentially

29
docs/getting-started.md
View File

@@ -6,8 +6,7 @@
5. [Validate](#validate) 5. [Validate](#validate)
6. [Next steps](#next-steps) 6. [Next steps](#next-steps)
Following these quick start instructions, you will have a basic setup that can perform recursive/federated lookups and Following these quick start instructions, you will have a basic setup that can perform recursive/federated lookups.
talk to the central Matrix.org Identity server.
This will be a good ground work for further integration with features and your existing Identity stores. This will be a good ground work for further integration with features and your existing Identity stores.
--- ---
@@ -24,13 +23,17 @@ You will need:
- Working Homeserver, ideally with working federation - Working Homeserver, ideally with working federation
- Reverse proxy with regular TLS/SSL certificate (Let's encrypt) for your mxisd domain - Reverse proxy with regular TLS/SSL certificate (Let's encrypt) for your mxisd domain
As synapse requires an HTTPS connection when talking to an Identity service, **a reverse proxy is required** as mxisd does If you use synapse:
not support HTTPS listener at this time. - It requires an HTTPS connection when talking to an Identity service, **a reverse proxy is required** as mxisd does
not support HTTPS listener at this time.
- HTTPS is hardcoded when talking to the Identity server. If your Identity server URL in your client is `https://matrix.example.org/`,
then you need to ensure `https://matrix.example.org/_matrix/identity/api/v1/...` will reach mxisd if called from the synapse host.
In doubt, test with `curl` or similar.
For maximum integration, it is best to have your Homeserver and mxisd reachable via the same hostname. For maximum integration, it is best to have your Homeserver and mxisd reachable via the same public hostname.
Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-matrix/mxisd/wiki/Gotchas#nating) if you use the same Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-matrix/mxisd/wiki/Gotchas#nating) if you use the same
hostname. host.
The following Quick Start guide assumes you will host the Homeserver and mxisd under the same hostname. The following Quick Start guide assumes you will host the Homeserver and mxisd under the same hostname.
If you would like a high-level view of the infrastructure and how each feature is integrated, see the If you would like a high-level view of the infrastructure and how each feature is integrated, see the
@@ -83,7 +86,7 @@ ProxyPass /_matrix/identity http://0.0.0.0:8090/_matrix/identity
Typical configuration would look like: Typical configuration would look like:
```apache ```apache
<VirtualHost *:443> <VirtualHost *:443>
ServerName example.org ServerName matrix.example.org
... ...
@@ -107,7 +110,7 @@ Typical configuration would look like:
```nginx ```nginx
server { server {
listen 443 ssl; listen 443 ssl;
server_name example.org; server_name matrix.example.org;
... ...
@@ -130,17 +133,17 @@ Add your mxisd domain into the `homeserver.yaml` at `trusted_third_party_id_serv
In a typical configuration, you would end up with something similar to: In a typical configuration, you would end up with something similar to:
```yaml ```yaml
trusted_third_party_id_servers: trusted_third_party_id_servers:
- example.org - matrix.example.org
``` ```
It is recommended to remove `matrix.org` and `vector.im` (or any other default entry) from your configuration so only It is **highly recommended** to remove `matrix.org` and `vector.im` (or any other default entry) from your configuration
your own Identity server is authoritative for your HS. so only your own Identity server is authoritative for your HS.
## Validate ## Validate
**NOTE:** In case your homeserver has no working federation, step 5 will not happen. If step 4 took place, consider **NOTE:** In case your homeserver has no working federation, step 5 will not happen. If step 4 took place, consider
your installation validated. your installation validated.
1. Log in using your Matrix client and set `https://example.org` as your Identity server URL, replacing `example.org` by 1. Log in using your Matrix client and set `https://matrix.example.org` as your Identity server URL, replacing `matrix.example.org`
the relevant hostname which you configured in your reverse proxy. by the relevant hostname which you configured in your reverse proxy.
2. Create a new empty room. All further actions will take place in this room. 2. Create a new empty room. All further actions will take place in this room.
3. Invite `mxisd-federation-test@kamax.io` 3. Invite `mxisd-federation-test@kamax.io`
4. The 3PID invite should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`. 4. The 3PID invite should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`.

6
docs/stores/exec.md
View File

@@ -39,7 +39,7 @@
| [Authentication](../features/authentication.md) | Yes | | [Authentication](../features/authentication.md) | Yes |
| [Directory](../features/directory.md) | Yes | | [Directory](../features/directory.md) | Yes |
| [Identity](../features/identity.md) | Yes | | [Identity](../features/identity.md) | Yes |
| [Profile](#profile) | Yes | | [Profile](../features/profile.md) | Yes |
This Identity Store lets you run arbitrary commands to handle the various requests in each support feature. This Identity Store lets you run arbitrary commands to handle the various requests in each support feature.
It is the most versatile Identity store of mxisd, allowing you to connect any kind of logic with any executable/script. It is the most versatile Identity store of mxisd, allowing you to connect any kind of logic with any executable/script.
@@ -199,7 +199,7 @@ exec:
DOMAIN: '{domain}' DOMAIN: '{domain}'
``` ```
With Authentication enabled, run `/opt/mxisd-exec/auth.sh` when validating credentials, providing: With Authentication enabled, run `/opt/mxisd-exec/auth.sh` when validating credentials, providing:
- A single command-line argument to provide the `localoart` as username - A single command-line argument to provide the `localpart` as username
- A plain text string with the password token for standard input, which will be replaced by the password to check - A plain text string with the password token for standard input, which will be replaced by the password to check
- A single environment variable `DOMAIN` containing Matrix ID domain, if given - A single environment variable `DOMAIN` containing Matrix ID domain, if given
@@ -207,7 +207,7 @@ The command will use the default values for:
- Success exit status of `0` - Success exit status of `0`
- Failure exit status of `1` - Failure exit status of `1`
- Any other exit status considered as error - Any other exit status considered as error
- The standard output processing as not processed - Standard output will not be processed
#### Advanced #### Advanced
Given the fictional `placeholder` feature: Given the fictional `placeholder` feature:

12
docs/stores/firebase.md
View File

@@ -2,12 +2,12 @@
https://firebase.google.com/ https://firebase.google.com/
## Features ## Features
| Name | Supported? | | Name | Supported |
|----------------|------------| |-------------------------------------------------|-----------|
| Authentication | Yes | | [Authentication](../features/authentication.md) | Yes |
| Directory | No | | [Directory](../features/directory.md) | No |
| Identity | Yes | | [Identity](../features/identity.md) | Yes |
| Profile | No | | [Profile](../features/profile.md) | No |
## Requirements ## Requirements
This backend requires a suitable Matrix client capable of performing Firebase authentication and passing the following This backend requires a suitable Matrix client capable of performing Firebase authentication and passing the following

20
docs/stores/ldap.md
View File

@@ -8,12 +8,12 @@
For NetIQ, replace all the `ldap` prefix in the configuration by `netiq`. For NetIQ, replace all the `ldap` prefix in the configuration by `netiq`.
## Features ## Features
| Name | Supported? | | Name | Supported |
|----------------|------------| |-------------------------------------------------|-----------|
| Authentication | Yes | | [Authentication](../features/authentication.md) | Yes |
| Directory | Yes | | [Directory](../features/directory.md) | Yes |
| Identity | Yes | | [Identity](../features/identity.md) | Yes |
| Profile | Yes | | [Profile](../features/profile.md) | Yes |
## Getting started ## Getting started
### Base ### Base
@@ -113,16 +113,18 @@ configuration item is needed to get started.
- `ldap.identity.medium`: Namespace to overwrite generated queries from the list of attributes for each 3PID medium. - `ldap.identity.medium`: Namespace to overwrite generated queries from the list of attributes for each 3PID medium.
### Authentication ### Authentication
No further configuration is needed to use the Authentication feature with LDAP once globally enabled and configured. After you have configured and enabled the [feature itself](../features/authentication.md), no further configuration is
needed with this identity store to make it work.
Profile auto-fill is enabled by default. It will use the `ldap.attribute.name` and `ldap.attribute.threepid` configuration Profile auto-fill is enabled by default. It will use the `ldap.attribute.name` and `ldap.attribute.threepid` configuration
options to get a lit of attributes to be used to build the user profile to pass on to synapse during authentication. options to get a lit of attributes to be used to build the user profile to pass on to synapse during authentication.
#### Configuration #### Configuration
- `ldap.auth.filter`: Specific user filter applied during identity search. Global filter is used if blank/not set. - `ldap.auth.filter`: Specific user filter applied during username search. Global filter is used if blank/not set.
### Directory ### Directory
No further configuration is needed to use the Directory feature with LDAP once globally enabled and configured. After you have configured and enabled the [feature itself](../features/directory.md), no further configuration is
needed with this identity store to make it work.
#### Configuration #### Configuration
To set a specific filter applied during directory search, use `ldap.directory.filter` To set a specific filter applied during directory search, use `ldap.directory.filter`

12
docs/stores/sql.md
View File

@@ -6,12 +6,12 @@
- SQLite - SQLite
## Features ## Features
| Name | Supported? | | Name | Supported |
|----------------|------------| |-------------------------------------------------|-----------|
| Authentication | No | | [Authentication](../features/authentication.md) | No |
| Directory | Yes | | [Directory](../features/directory.md) | Yes |
| Identity | Yes | | [Identity](../features/identity.md) | Yes |
| Profile | Yes | | [Profile](../features/profile.md) | Yes |
Due to the implementation complexity of supporting arbitrary hashing/encoding mechanisms or auth flow, Authentication Due to the implementation complexity of supporting arbitrary hashing/encoding mechanisms or auth flow, Authentication
will be out of scope of SQL Identity stores and should be done via one of the other identity stores, typically will be out of scope of SQL Identity stores and should be done via one of the other identity stores, typically

12
docs/stores/synapse.md
View File

@@ -2,12 +2,12 @@
Synapse's Database itself can be used as an Identity store. Synapse's Database itself can be used as an Identity store.
## Features ## Features
| Name | Supported? | | Name | Supported |
|----------------|------------| |-------------------------------------------------|-----------|
| Authentication | No | | [Authentication](../features/authentication.md) | No |
| Directory | Yes | | [Directory](../features/directory.md) | Yes |
| Identity | Yes | | [Identity](../features/identity.md) | Yes |
| Profile | Yes | | [Profile](../features/profile.md) | Yes |
Authentication is done by Synapse itself. Authentication is done by Synapse itself.

12
docs/stores/wordpress.md
View File

@@ -5,12 +5,12 @@ Two types of connections are required for full support:
- Direct SQL access - Direct SQL access
## Features ## Features
| Name | Supported? | | Name | Supported |
|----------------|------------| |-------------------------------------------------|-----------|
| Authentication | Yes | | [Authentication](../features/authentication.md) | Yes |
| Directory | Yes | | [Directory](../features/directory.md) | Yes |
| Identity | Yes | | [Identity](../features/identity.md) | Yes |
| Profile | No | | [Profile](../features/profile.md) | No |
## Requirements ## Requirements
- [Wordpress](https://wordpress.org/download/) >= 4.4 - [Wordpress](https://wordpress.org/download/) >= 4.4