|
|
|
|
@@ -15,12 +15,15 @@ mxisd - Federated Matrix Identity Server Daemon
|
|
|
|
|
mxisd is a Federated Matrix Identity server for self-hosted Matrix infrastructures with enhanced features.
|
|
|
|
|
|
|
|
|
|
It is specifically designed to connect to an Identity store (AD/Samba/LDAP, SQL Database, Web services/application, ...)
|
|
|
|
|
to ease integration of the Matrix ecosystem with an existing infrastructure, or to build a new one using lasting tools.
|
|
|
|
|
and ease the integration of the Matrix ecosystem with an existing infrastructure, or to build a new one using lasting
|
|
|
|
|
tools.
|
|
|
|
|
|
|
|
|
|
mxisd core principle is to map between Matrix IDs and 3PIDs (Thrid-party Identifiers) for the Homeserver and its users.
|
|
|
|
|
3PIDs can be anything that identify a user, like:
|
|
|
|
|
The core principle of mxisd is to map between Matrix IDs and 3PIDs (Thrid-party Identifiers) for the Homeserver and its
|
|
|
|
|
users. 3PIDs can be anything that identify a user, like:
|
|
|
|
|
- Full name
|
|
|
|
|
- Email address
|
|
|
|
|
- Phone number
|
|
|
|
|
- Employee number
|
|
|
|
|
- Skype/Live ID
|
|
|
|
|
- Twitter handle
|
|
|
|
|
- Facebook ID
|
|
|
|
|
@@ -29,6 +32,9 @@ mxisd core principle is to map between Matrix IDs and 3PIDs (Thrid-party Identif
|
|
|
|
|
mxisd is an enhanced Identity service, which implements the [Matrix Identity service API](https://matrix.org/docs/spec/identity_service/unstable.html)
|
|
|
|
|
but also several other features that greatly enhance user experience within Matrix.
|
|
|
|
|
|
|
|
|
|
mxisd is the one stop shop for anything regarding Authentication, Directory and Identity management in Matrix built as a
|
|
|
|
|
single coherent product.
|
|
|
|
|
|
|
|
|
|
# Features
|
|
|
|
|
As a [regular Matrix Identity service](docs/features/identity.md):
|
|
|
|
|
- Search for people by 3PID using its own Identity stores (LDAP, SQL, etc.)
|
|
|
|
|
@@ -42,17 +48,17 @@ As an enhanced Identity service:
|
|
|
|
|
- Federated Identity servers, if applicable to the 3PID
|
|
|
|
|
- Arbitrary Identity servers
|
|
|
|
|
- Central Matrix Identity servers
|
|
|
|
|
- [Extensive control of where 3PIDs are transmited](docs/sessions/3pid.md), so they are not leaked publicly by users
|
|
|
|
|
- [Extensive control of where 3PIDs are transmited](docs/sessions/3pid.md), so they are not leaked publicly by users
|
|
|
|
|
- [Authentication support](docs/features/authentication.md) for [synapse](https://github.com/matrix-org/synapse) via the
|
|
|
|
|
[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth).
|
|
|
|
|
[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth)
|
|
|
|
|
- [Directory integration](docs/features/directory-users.md) which allows you to search for users within your
|
|
|
|
|
organisation, even without prior Matrix contact.
|
|
|
|
|
organisation, even without prior Matrix contact
|
|
|
|
|
- [Auto-fill of user profile](docs/features/authentication.md) (Display name, 3PIDs) via the
|
|
|
|
|
[REST auth module](https://github.com/kamax-io/matrix-synapse-rest-auth)
|
|
|
|
|
|
|
|
|
|
# Why use mxisd
|
|
|
|
|
- Use your existing Identity store, do not duplicate information
|
|
|
|
|
- Auto-fill user profiles with relevant info
|
|
|
|
|
- Auto-fill user profiles with relevant information
|
|
|
|
|
- As an organisation, stay in control of 3PIDs so they are not published to the central Matrix.org servers where they
|
|
|
|
|
currently **cannot be removed**
|
|
|
|
|
- Users can directly find each other using whatever attribute is relevant within your Identity store
|
|
|
|
|
@@ -83,7 +89,9 @@ You can also use a dedicated domain for mxisd, but will not have access to some
|
|
|
|
|
Be aware of a [NAT/Reverse proxy gotcha](https://github.com/kamax-io/mxisd/wiki/Gotchas#nating) if you use the same
|
|
|
|
|
hostname.
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
[dedicated document](docs/architecture.md)
|
|
|
|
|
|
|
|
|
|
## Install
|
|
|
|
|
Install via:
|
|
|
|
|
@@ -108,9 +116,10 @@ If your HS/mxisd hostname is not the same as your Matrix domain, configure `serv
|
|
|
|
|
Complete configuration guide is available [here](docs/configure.md).
|
|
|
|
|
|
|
|
|
|
## Integrate
|
|
|
|
|
For an overview of a typical mxisd infrastructure, see the [dedicated document](docs/architecture.md)
|
|
|
|
|
### Reverse proxy
|
|
|
|
|
#### Apache2
|
|
|
|
|
In the VirtualHost handling the domain with SSL, add the following line, replacing `0.0.0.0` by the right address/host.
|
|
|
|
|
In the VirtualHost handling the domain with SSL, add the following line and replace `0.0.0.0` by the right address/host.
|
|
|
|
|
**This line MUST be present before the one for the homeserver!**
|
|
|
|
|
```
|
|
|
|
|
ProxyPass /_matrix/identity http://0.0.0.0:8090/_matrix/identity
|
|
|
|
|
@@ -146,9 +155,10 @@ See the [dedicated document](docs/features/federation.md).
|
|
|
|
|
## Validate
|
|
|
|
|
Log in using your Matrix client and set `https://example.org` as your Identity server URL, replacing `example.org` by
|
|
|
|
|
the relevant hostname which you configured in your reverse proxy.
|
|
|
|
|
|
|
|
|
|
Try to invite `mxisd-lookup-test@kamax.io`, which should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`
|
|
|
|
|
Try to invite `mxisd-lookup-test@kamax.io`, which should be turned into a Matrix invite to `@mxisd-lookup-test:kamax.io`
|
|
|
|
|
|
|
|
|
|
If it worked, it means you are up and running and can enjoy mxisd in its basic mode! Congratulations!
|
|
|
|
|
If it did not work, [get in touch](#support) and we'll do our best to get you started.
|
|
|
|
|
|
|
|
|
|
You can now integrate mxisd further with your infrastructure using the various [features](docs/README.md) guides.
|
|
|
|
|
|
|
|
|
|
@@ -170,36 +180,47 @@ First and foremost, the best way to contribute is to use mxisd and tell us about
|
|
|
|
|
We would love to hear about your experience and get your feedback on how to make it an awesome product.
|
|
|
|
|
|
|
|
|
|
You can contribute as a community member by:
|
|
|
|
|
- Opening issues for any weird behaviour or bug. mxisd should feel natural, let us know if it doesn't!
|
|
|
|
|
- Opening issues for any weird behaviour or bug. mxisd should feel natural, let us know if it does not!
|
|
|
|
|
- Helping us improve the documentation: tell us what is good or not good (in an issue or in Matrix), or make a PR with
|
|
|
|
|
changes you feel improve the doc
|
|
|
|
|
- Contribute code directly: we love contributors! We are quite strict in our reviews but and we'll always review your PR
|
|
|
|
|
in a timely fashion.
|
|
|
|
|
changes you feel improve the doc.
|
|
|
|
|
- Contribute code directly: we love contributors! All your contributions will be licensed under AGPLv3.
|
|
|
|
|
- Donate! any donation is welcome, regardless how small or big. This will directly be used for the fixed costs and
|
|
|
|
|
developer time.
|
|
|
|
|
|
|
|
|
|
You can contribute as an organisation/corporation by:
|
|
|
|
|
- Get a [support contract](#support-professional). This is the best way you can help us as it ensures mxisd is maintained regularly and you get
|
|
|
|
|
direct access to the support team.
|
|
|
|
|
- Sponsoring new features or bug fixes. We'll quote the cost of development, at a reduced rate, and maintain the code
|
|
|
|
|
in future release of mxisd. (subject to approval of the feature on our end)
|
|
|
|
|
- Get a [support contract](#support-professional). This is the best way you can help us as it ensures mxisd is
|
|
|
|
|
maintained regularly and you get direct access to the support team.
|
|
|
|
|
- Sponsoring new features or bug fixes. [Get in touch](#contact) so we can discuss it further.
|
|
|
|
|
|
|
|
|
|
# FAQ
|
|
|
|
|
### Do I need to use mxisd if I run a Homeserver?
|
|
|
|
|
No, but it is recommended, even if you don't use any backends or integration.
|
|
|
|
|
|
|
|
|
|
mxisd in its default configuration will use federation and involve the central Matrix.org Identity servers when
|
|
|
|
|
performing queries, giving you access to at least the same information than if you were not running it.
|
|
|
|
|
performing queries, giving you access to at 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 doesn't change what you already know, just adds some nice
|
|
|
|
|
simple features on top of it.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
### 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) only handles on specific flow:
|
|
|
|
|
validate credentials at login.
|
|
|
|
|
|
|
|
|
|
It does not:
|
|
|
|
|
- Auto-provision user profiles
|
|
|
|
|
- Integrate with Identity management
|
|
|
|
|
- Integrate with Directory searches
|
|
|
|
|
- Protect you against the username case sensitivites issues in synapse
|
|
|
|
|
|
|
|
|
|
mxisd is a replacement and enhancement of it, and also offers coherent results in all areas, which LDAP3 auth provider
|
|
|
|
|
does not.
|
|
|
|
|
|
|
|
|
|
### I saw that sydent is the official Identity server implemenation of the Matrix team, I should use that!
|
|
|
|
|
You can, but [sydent](https://github.com/matrix-org/sydent):
|
|
|
|
|
- [was never meant to be self-hosted and should not be done](https://github.com/matrix-org/sydent/issues/22)
|
|
|
|
|
- [should not be used and/or self-hosted](https://github.com/matrix-org/sydent/issues/22)
|
|
|
|
|
- is not meant to be linked to a specific Homeserver / domain
|
|
|
|
|
- cannot handle federation or proxy lookups, effectively isolating your users from the rest of the network
|
|
|
|
|
- forces you to duplicate all your identity data, so people can be found by 3PIDs
|
|
|
|
|
@@ -209,18 +230,18 @@ So really, you should go with mxisd.
|
|
|
|
|
|
|
|
|
|
### I'm not sure I understand what an "Identity server" is supposed to be or do
|
|
|
|
|
The current Identity service API is more a placeholder, as the Matrix devs did not have time so far to really work on
|
|
|
|
|
what they want to do with that part of the ecosystem. Therefore, "Identity" is a missleading word currently.
|
|
|
|
|
Given the scope of the current Identity Service API, their would be best called "Directory and Invitation service".
|
|
|
|
|
what they want to do with that part of the ecosystem. Therefore, "Identity" is a misleading word currently.
|
|
|
|
|
Given the scope of the current Identity Service API, it would be best called "Invitation service".
|
|
|
|
|
|
|
|
|
|
Because the current scope is so limited and no integration is done with the Homeserver, there was a big lack of features
|
|
|
|
|
for groups/corporations/organisation. This is where mxisd comes in.
|
|
|
|
|
|
|
|
|
|
mxisd implements the Identity Service API and also a set of features which are expected by regular users, truely living
|
|
|
|
|
mxisd implements the Identity Service API and also a set of features which are expected by regular users, truly living
|
|
|
|
|
up to its "Identity server" name.
|
|
|
|
|
|
|
|
|
|
### So mxisd is just a big hack! I don't want to use non-official features!
|
|
|
|
|
mxisd primary concern is to always be compatible with the Matrix ecosystem and the Identity service API.
|
|
|
|
|
Whenever the API will be updated and/or enchanced, mxisd will follow, remaining 100% compatible with the ecosystem.
|
|
|
|
|
Whenever the API will be updated and/or enhanced, mxisd will follow, remaining 100% compatible with the ecosystem.
|
|
|
|
|
|
|
|
|
|
We also directly talk with the Matrix developers to ensure all features we implement have their approval, and that we
|
|
|
|
|
are in line with their vision of Identity management within the Matrix ecosystem.
|
|
|
|
|
@@ -232,4 +253,6 @@ the door to very nice enhancements and integrations.
|
|
|
|
|
No
|
|
|
|
|
|
|
|
|
|
# Contact
|
|
|
|
|
Get in touch on Matrix: [#mxisd:kamax.io](https://matrix.to/#/#mxisd:kamax.io)
|
|
|
|
|
Get in touch via:
|
|
|
|
|
- Matrix at [#mxisd:kamax.io](https://matrix.to/#/#mxisd:kamax.io)
|
|
|
|
|
- Email, see our website: [Kamax.io](https://www.kamax.io)
|
|
|
|
|
|
Maxime Dor