Mercurial > prosody-modules

comparison mod_auth_token/README.md @ 2956:d0ca211e1b0e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
New HMAC token authentication module for Prosody.
author JC Brand <jc@opkode.com>
date Tue, 27 Mar 2018 10:48:04 +0200
parents
children
comparison
equal deleted inserted replaced
2938:f000ba14d531 2956:d0ca211e1b0e
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 ## How to generate the token
15
16 You'll need a shared OTP_SEED value for generating time-based one-time-pin
17 values and a shared private key for signing the HMAC token.
18
19 You can generate the OTP_SEED value with Python, like so:
20
21 >>> import pyotp
22 >>> pyotp.random_base32()
23 u'XVGR73KMZH2M4XMY'
24
25 and the shared secret key as follows:
26
27 >>> import pyotp
28 >>> pyotp.random_base32(length=32)
29 u'JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7'
30
31 These values then need to go into your Prosody.cfg file:
32
33 token_secret = "JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7"
34 otp_seed = "XVGR73KMZH2M4XMY"
35
36 The application that generates the tokens also needs access to these values.
37
38 For an example on how to generate a token, take a look at the `generate_token`
39 function in the `test_token_auth.lua` file inside this directory.
40
41 ## Custom SASL auth
42
43 This module depends on a custom SASL auth mechanism called X-TOKEN and which
44 is provided by the file `mod_sasl_token.lua`.
45
46 Prosody doesn't automatically pick up this file, so you'll need to update your
47 configuration file's `plugin_paths` to link to this subdirectory (for example
48 to `/usr/lib/prosody-modules/mod_auth_token/`).