Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updating mod_keystore and mod_auth_token documentation #4354

Merged
merged 1 commit into from
Aug 6, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion doc/modules/mod_auth_token.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Validity period configuration for provision tokens happens outside the module si

### Required keys

To read more about the keys MongooseIM makes use of, please refer to [mod_keystore](mod_keystore.md) documentation.
To read more about the keys MongooseIM makes use of, please refer to [mod_keystore](mod_keystore.md) documentation, where you can find an example configuration when using `mod_auth_token`.

## Token types

Expand All @@ -49,19 +49,22 @@ Three token types are supported:
Access tokens can be used as a payload for the X-OAUTH authentication mechanism and grant access to the system.
Access tokens can't be revoked.
An access token is valid only until its expiry date is reached.
In mod_keystore, the keyname for this token type is `token_secret`.

- _refresh tokens_: These are longer lived tokens which are tracked by the server and therefore require persistent storage in a relational database.
Refresh tokens can be used as a payload for the X-OAUTH authentication mechanism and to grant access to the system.
Also they can result in a new set of tokens being returned upon successful authentication.
They can be revoked - if a refresh token hasn't been revoked, it is valid until it has expired.
On revocation, it immediately becomes invalid.
As the server stores information about granted tokens, it can also persistently mark them as revoked.
In mod_keystore, the keyname for this token type is `token_secret`.

- _provision tokens_: These tokens are generated by a service external to the server.
They grant the owner a permission to create an account.
A provision token may contain information which the server can use to provision the VCard for the newly created account.
Using a provision token to create an account (and inject VCard data) is done similarly to other token types, i.e. by passing it as payload for the X-OAUTH mechanism.
The XMPP server has no way of tracking and revoking provision tokens, as they come from an outside source.
In mod_keystore, the keyname for this token type is `provision_pre_shared`. The usage of this token type is optional.

## Token serialization format

Expand Down
7 changes: 7 additions & 0 deletions doc/modules/mod_keystore.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,3 +75,10 @@ for each virtual XMPP domain):
{name = "access_psk", type = "file", path = "priv/second_access_psk"},
{name = "provision_psk", type = "file", path = "priv/second_provision_psk"}]
```

Minimal configuration supporting mod_auth_token:

```toml
[modules.mod_keystore]
keys = [{name = "token_secret", type = "ram"}]
```