For instances where an organisation doesn’t have their users in their Matrix instance already and/or they want Moodle to create users as required, we need a way to have Moodle create them.

As part of this Moodle LMS will NOT be managing the passwords of these users, and we won’t be using Moodle LMS as an IdP.

User stories:

1. As an admin I want to be able to configure Moodle to create users in Matrix for my users in Moodle. So my Moodle users can connect to my organisation’s Matrix instance.
2. As an admin when configuring Moodle to create users in Matrix I want to define the users login type in Matrix (SSO or password). So my users can log in correctly to my organisation's Matrix instance.
3. As an admin I want to be able to map an existing user profile field to a Matrix unique identifier. So that when a user in Moodle performs a Matrix related action they are correctly identified in Matrix.

Plugin settings form fields

There will need to be several plugin setting form fields that will need to be created to support the functionality.

Because some fields will only be applicable based on the settings of other fields in the form, hiding (or disabling) fields should be used.

• Matrix user id
  • The Moodle user profile field that stores the Matrix user id (@<username>:<homeserver> ).
  • Dropdown of all available Moodle user profile fields
  • Defaults to user profile field created by plugin

• Create users in Matrix
  • Checkbox (or maybe yes/no select)
  • When selected Moodle will create users in Matrix if the user does not already exist on the Matrix Homeserver and the “Matrix user id” profile field in Moodle is empty.

• User Matrix authentication
  • Hidden unless “Create users in Matrix” is enabled
  • Select how users authenticate to Matrix. This needs to be known so the Matrix user account can be created correctly
  • Dropdown select with the following values:
    • Manual
    • SSO via OIDC

• Matrix OIDC IdP ID
  • Text field that contains the ‘idp_id’ value from the Synapse homeserver (homeserver.yaml) configuration file for the IdP the users will log into Matrix via.
  • This is a required field
  • Hidden unless “SSO via OIDC” is select for “User Matrix authentication”

• OIDC Provider unique ID
  • Dropdown of all available Moodle user profile fields
  • Each OIDC provider will have a field whose value uniqiuely identifiers a user. The value of this field needs to be provided when the user is created.
  • This is a required field
  • Hidden unless “SSO via OIDC” is select for “User Matrix authentication”

Matrix user id

We always need to have a user profile field that contains the matrix user id, even Moodle is not creating Matrix users.  The Matrix user ID in Moodle is how the Moodle user account and the Matrix accounts are linked. The format of the Matrix user id is: @<username>:<homeserver>

If Moodle is creating the Matrix users for an org, then Moodle will populate this field at user creation time.
If Moodle is NOT creating the Matrix users, then an admin should populate this filed with the Matrix user ID for that user
Only create users in Matrix for Moodle users who have an empty Matrix user id field
If the Matrix ID field in Moodle is NOT empty do not create a user in matrix. This is so orgs can have some users already in Matrix and/or manage some users manually.

SSO Authentication

Synapse supports several methods of SSO: OIDC(OAuth2), SAML2, and CAS. However, for an initial implementation we’re only supporting OAuth2 as the SSO method. This will make the code and administration interface on the Moodle side less complicated.

API Calls:

Below are sample cURL calls to create and get users in Matrix using the Synapse API. NOTE: We'll use the Synapse not Matrix API for this.

Minimal example of creating a user:

curl --header "Authorization: Bearer syt_YWRtaW4_lshIQPQAFwUvxXYhBEha_41M0ju" \

-X PUT \

-d '{"displayname":"testuser"}' \

https://synapse:8008/_synapse/admin/v2/users/@testuser:synapse

This user won’t actually be able to login, unless an admin sets a password for them. As there is no email set for them to use the Element reset password and they are not configured to use an SSO provider.

An example to create a user with an email address and SSO server details:

curl --header "Authorization: Bearer syt_YWRtaW4_lshIQPQAFwUvxXYhBEha_41M0ju" \

-X PUT \

-d '{"displayname":"testuser","threepids":[

],"external_ids":[

]}' \

https://synapse:8008/_synapse/admin/v2/users/@testuser:synapse

• In the URL a user ID (username) must be provided, in the format @<username>:<homeserver> 
• In the JSON payload:
•  “displayname” is the user's name displayed in Matrix. We should set this as: firstname + “ “ + lastname 
• “auth_provider” is the value of “idp_id” in the home servers yaml configuration file with “oidc-”, “saml2-”, or “cas-” prefixed depending on the type of SSO used.
• “External_id” is a unique identifier for the user. Defaults to 'sub', which OpenID Connect compliant providers should provide.  This will need to be mapped to a Moodle user profile field

Getting a single user is:

curl --header "Authorization: Bearer syt_YWRtaW4_lshIQPQAFwUvxXYhBEha_41M0ju" \

-X GET https://synapse:8008/_synapse/admin/v2/users/@testuser:synapse

The relevant Synapse API doc is: https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#user-admin-api