You've already forked authentication-service
mirror of
https://github.com/matrix-org/matrix-authentication-service.git
synced 2025-07-03 07:22:32 +03:00
82 lines
2.5 KiB
Markdown
82 lines
2.5 KiB
Markdown
# Using the service
|
|
|
|
## Running
|
|
|
|
Once the configuration is done, one should run the database migrations
|
|
(database schema upgrade, also for setup) by running
|
|
|
|
```sh
|
|
mas-cli database migrate
|
|
```
|
|
|
|
The server can then be started by running
|
|
|
|
```sh
|
|
mas-cli server
|
|
```
|
|
|
|
```
|
|
Sep 24 14:42:42.743 INFO mas_cli::server: Starting task scheduler
|
|
Sep 24 14:42:42.743 INFO mas_core::templates: Loading builtin templates
|
|
Sep 24 14:42:42.752 INFO mas_cli::server: Listening on http://0.0.0.0:8080
|
|
```
|
|
|
|
The server should now be accessible through <http://localhost:8080/>.
|
|
|
|
**Note**: when running with Docker, the port used by the server should be exposed with the `-p` flag:
|
|
|
|
```sh
|
|
docker run --rm \
|
|
-v `pwd`/config.yaml:/config.yaml \
|
|
-p 8080:8080 \
|
|
ghcr.io/matrix-org/matrix-authentication-service:main \
|
|
server
|
|
```
|
|
|
|
## Registering, logging in and out
|
|
|
|
Through the interface, users are able to create an account by clicking the `Register` button on the top right (or going to [`/register`](http://localhost:8080/register)).
|
|
They can then end their session by clicking the `Sign out` button and sign back in.
|
|
|
|
## Playing around with the playground
|
|
|
|
The OpenID Foundation hosts a OpenID Connect Playground where one can test logging in through an OIDC provider: https://openidconnect.net/
|
|
|
|
### Step 1: Add the client to the server config
|
|
|
|
Add the following section to the server configuration file `config.yaml`:
|
|
|
|
```yaml
|
|
clients:
|
|
# The client ID must be a valid ULID
|
|
- client_id: 000000000000OIDCPLAYGROUND
|
|
client_secret: verysecret
|
|
redirect_uris:
|
|
- "https://openidconnect.net/callback"
|
|
```
|
|
|
|
Sync the configuration with the database:
|
|
|
|
```sh
|
|
mas-cli config sync
|
|
```
|
|
|
|
### Step 2: Change the playground configuration
|
|
|
|
- Navigate to [the playground](https://openidconnect.net/)
|
|
- Click on "Configuration"
|
|
- Server template: *Custom*
|
|
- Paste the discovery document URL found on the service homepage (e.g. `http://localhost:8080/.well-known/openid-configuration`)
|
|
- Click "Use discovery document" ; it should fill out the authorization, token and token keys endpoints
|
|
- Set the OIDC Client ID to `000000000000OIDCPLAYGROUND` and the Client Secret to `verysecret` (must match the ones in the configuration)
|
|
- Click "Save"
|
|
|
|
### Step 3: Run the OpenID Connect flow
|
|
|
|
Start the flow by clicking the "Start" button.
|
|
It should redirect the browser to the authentication service.
|
|
If a user is already logged in, it should redirect back to the playground immediately.
|
|
|
|
Follow the flow to see the code exchange happen.
|
|
Note that the last step only works if the service is accessible through the internet.
|