prosody-modules
06fbbd45ba75
mod_auth_token/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_auth_token/README.md @ 6302:06fbbd45ba75

mod_cloud_notify: Readme: fix links and labels that were removed in the last commit diff --git a/mod_cloud_notify/README.md b/mod_cloud_notify/README.md --- a/mod_cloud_notify/README.md +++ b/mod_cloud_notify/README.md @@ -1,3 +1,9 @@ +---- +-labels: +-- 'Stage-Beta' +-summary: 'XEP-0357: Cloud push notifications' +---- + # Introduction This module enables support for sending "push notifications" to clients @@ -32,15 +38,15 @@ notification to your device. When your d it will display it or wake up the app so it can connect to XMPP and receive any pending messages. -This protocol is described for developers in \[XEP-0357: Push -Notifications\]. +This protocol is described for developers in [XEP-0357: Push +Notifications]. -For this module to work reliably, you must have \[mod_smacks\], -\[mod_mam\] and \[mod_carbons\] also enabled on your server. +For this module to work reliably, you must have [mod_smacks], +[mod_mam] and [mod_carbons] also enabled on your server. Some clients, notably Siskin and Snikket iOS need some additional extensions that are not currently defined in a standard XEP. To support -these clients, see \[mod_cloud_notify_extensions\]. +these clients, see [mod_cloud_notify_extensions]. # Configuration @@ -58,18 +64,18 @@ these clients, see \[mod_cloud_notify_ex # Internal design notes App servers are notified about offline messages, messages stored by -\[mod_mam\] or messages waiting in the smacks queue. The business rules +[mod_mam] or messages waiting in the smacks queue. The business rules outlined [here](//mail.jabber.org/pipermail/standards/2016-February/030925.html) are all honored[^2]. -To cooperate with \[mod_smacks\] this module consumes some events: +To cooperate with [mod_smacks] this module consumes some events: `smacks-ack-delayed`, `smacks-hibernation-start` and `smacks-hibernation-end`. These events allow this module to send out notifications for messages received while the session is hibernated by -\[mod_smacks\] or even when smacks acknowledgements for messages are +[mod_smacks] or even when smacks acknowledgements for messages are delayed by a certain amount of seconds configurable with the -\[mod_smacks\] setting `smacks_max_ack_delay`. +[mod_smacks] setting `smacks_max_ack_delay`. The `smacks_max_ack_delay` setting allows to send out notifications to clients which aren't already in smacks hibernation state (because the
author Menel <menel@snikket.de>
date Fri, 13 Jun 2025 10:44:37 +0200
parent 6003:fe081789f7b5
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2956
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
1 # mod_auth_token
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
2
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
3 This module enables Prosody to authenticate time-based one-time-pin (TOTP) HMAC tokens.
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
4
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
5 This is an alternative to "external authentication" which avoids the need to
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
6 make a blocking HTTP call to the external authentication service (usually a web application backend).
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
7
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
8 Instead, the application generates the HMAC token, which is then sent to
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
9 Prosody via the XMPP client and Prosody verifies the authenticity of this
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
10 token.
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
11
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
12 If the token is verified, then the user is authenticated.
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
13
3471
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
14 ## Luarocks dependencies
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
15
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
16 You'll need to install the following luarocks
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
17
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
18 otp 0.1-5
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
19 luatz 0.3-1
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
20
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
21 ## How to generate the TOTP seed and shared signing secret
2956
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
22
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
23 You'll need a shared OTP_SEED value for generating time-based one-time-pin
3471
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
24 (TOTP) values and a shared private key for signing the HMAC token.
2956
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
25
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
26 You can generate the OTP_SEED value with Python, like so:
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
27
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
28 >>> import pyotp
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
29 >>> pyotp.random_base32()
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
30 u'XVGR73KMZH2M4XMY'
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
31
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
32 and the shared secret key as follows:
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
33
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
34 >>> import pyotp
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
35 >>> pyotp.random_base32(length=32)
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
36 u'JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7'
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
37
3471
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
38 ## Configuration
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
39
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
40 Firest you need to enable the relevant modules to your Prosody.cfg file.
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
41
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
42 Look for the line `modules_enabled` (either globally or for your
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
43 particular `VirtualHost`), and then add the following to tokens:
2956
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
44
3471
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
45 modules_enabled = {
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
46 -- Token authentication
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
47 "auth_token";
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
48 "sasl_token";
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
49 }
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
50
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
51 The previously generated token values also need to go into your Prosody.cfg file:
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
52
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
53 authentication = "token";
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
54 token_secret = "JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7";
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
55 otp_seed = "XVGR73KMZH2M4XMY";
2956
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
56
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
57 The application that generates the tokens also needs access to these values.
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
58
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
59 For an example on how to generate a token, take a look at the `generate_token`
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
60 function in the `test_token_auth.lua` file inside this directory.
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
61
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
62 ## Custom SASL auth
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
63
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
64 This module depends on a custom SASL auth mechanism called X-TOKEN and which
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
65 is provided by the file `mod_sasl_token.lua`.
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
66
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
67 Prosody doesn't automatically pick up this file, so you'll need to update your
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
68 configuration file's `plugin_paths` to link to this subdirectory (for example
d0ca211e1b0e New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff changeset
69 to `/usr/lib/prosody-modules/mod_auth_token/`).
3471
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
70
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
71 ## Generating the token
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
72
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
73 Here's a Python snippet showing how you can generate the token that Prosody
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
74 will then verify:
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
75
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
76 import base64
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
77 import pyotp
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
78 import random
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
79
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
80 # Constants
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
81 OTP_INTERVAL = 30
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
82 OTP_DIGITS = 8
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
83
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
84 jid = '{}@{}'.format(username, domain)
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
85
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
86 otp_service = pyotp.TOTP(
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
87 OTP_SEED, # OTP_SEED must be set to the value generated previously (see above)
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
88 digits=OTP_DIGITS,
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
89 interval=OTP_INTERVAL
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
90 )
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
91 otp = otp_service.generate_otp(otp_service.timecode(datetime.utcnow()))
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
92
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
93 nonce = ''.join([str(random.randint(0, 9)) for i in range(32)])
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
94 string_to_sign = otp + nonce + jid
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
95 signature = hmac.new(token_secret, string_to_sign, hashlib.sha256).digest()
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
96 token = u"{} {}".format(otp+nonce, base64.b64encode(signature))
b4bcb84997e7 mod_auth_token: Update README.
JC Brand <jc@opkode.com>
parents: 2960
diff changeset
97