prosody-modules
fe081789f7b5
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

Comparison

mod_auth_token/README.md @ 6003:fe081789f7b5

All community modules: Unify file extention of Markdown files to .md
author Menel <menel@snikket.de>
date Tue, 22 Oct 2024 10:26:01 +0200
parent 3471:mod_auth_token/README.markdown@b4bcb84997e7
comparison
equal deleted inserted replaced
6002:5a65a632d5b9 6003:fe081789f7b5
1 # mod_auth_token
2
3 This module enables Prosody to authenticate time-based one-time-pin (TOTP) HMAC tokens.
4
5 This is an alternative to "external authentication" which avoids the need to
6 make a blocking HTTP call to the external authentication service (usually a web application backend).
7
8 Instead, the application generates the HMAC token, which is then sent to
9 Prosody via the XMPP client and Prosody verifies the authenticity of this
10 token.
11
12 If the token is verified, then the user is authenticated.
13
14 ## Luarocks dependencies
15
16 You'll need to install the following luarocks
17
18 otp 0.1-5
19 luatz 0.3-1
20
21 ## How to generate the TOTP seed and shared signing secret
22
23 You'll need a shared OTP_SEED value for generating time-based one-time-pin
24 (TOTP) values and a shared private key for signing the HMAC token.
25
26 You can generate the OTP_SEED value with Python, like so:
27
28 >>> import pyotp
29 >>> pyotp.random_base32()
30 u'XVGR73KMZH2M4XMY'
31
32 and the shared secret key as follows:
33
34 >>> import pyotp
35 >>> pyotp.random_base32(length=32)
36 u'JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7'
37
38 ## Configuration
39
40 Firest you need to enable the relevant modules to your Prosody.cfg file.
41
42 Look for the line `modules_enabled` (either globally or for your
43 particular `VirtualHost`), and then add the following to tokens:
44
45 modules_enabled = {
46 -- Token authentication
47 "auth_token";
48 "sasl_token";
49 }
50
51 The previously generated token values also need to go into your Prosody.cfg file:
52
53 authentication = "token";
54 token_secret = "JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7";
55 otp_seed = "XVGR73KMZH2M4XMY";
56
57 The application that generates the tokens also needs access to these values.
58
59 For an example on how to generate a token, take a look at the `generate_token`
60 function in the `test_token_auth.lua` file inside this directory.
61
62 ## Custom SASL auth
63
64 This module depends on a custom SASL auth mechanism called X-TOKEN and which
65 is provided by the file `mod_sasl_token.lua`.
66
67 Prosody doesn't automatically pick up this file, so you'll need to update your
68 configuration file's `plugin_paths` to link to this subdirectory (for example
69 to `/usr/lib/prosody-modules/mod_auth_token/`).
70
71 ## Generating the token
72
73 Here's a Python snippet showing how you can generate the token that Prosody
74 will then verify:
75
76 import base64
77 import pyotp
78 import random
79
80 # Constants
81 OTP_INTERVAL = 30
82 OTP_DIGITS = 8
83
84 jid = '{}@{}'.format(username, domain)
85
86 otp_service = pyotp.TOTP(
87 OTP_SEED, # OTP_SEED must be set to the value generated previously (see above)
88 digits=OTP_DIGITS,
89 interval=OTP_INTERVAL
90 )
91 otp = otp_service.generate_otp(otp_service.timecode(datetime.utcnow()))
92
93 nonce = ''.join([str(random.randint(0, 9)) for i in range(32)])
94 string_to_sign = otp + nonce + jid
95 signature = hmac.new(token_secret, string_to_sign, hashlib.sha256).digest()
96 token = u"{} {}".format(otp+nonce, base64.b64encode(signature))
97