author | Kim Alvefur <zash@zash.se> |
Sun, 20 May 2018 18:11:15 +0200 | |
changeset 3037 | b2b129f699ed |
parent 2964 | b8834fec4b7e |
child 3475 | b4bcb84997e7 |
permissions | -rw-r--r-- |
2960
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 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
14 |
## How to generate the token |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
15 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
16 |
You'll need a shared OTP_SEED value for generating time-based one-time-pin |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
17 |
values and a shared private key for signing the HMAC token. |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
18 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
19 |
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
|
20 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
21 |
>>> import pyotp |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
22 |
>>> pyotp.random_base32() |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
23 |
u'XVGR73KMZH2M4XMY' |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
24 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
25 |
and the shared secret key as follows: |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
26 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
27 |
>>> import pyotp |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
28 |
>>> pyotp.random_base32(length=32) |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
29 |
u'JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7' |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
30 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
31 |
These values then need to go into your Prosody.cfg file: |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
32 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
33 |
token_secret = "JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7" |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
34 |
otp_seed = "XVGR73KMZH2M4XMY" |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
35 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
36 |
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
|
37 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
38 |
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
|
39 |
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
|
40 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
41 |
## Custom SASL auth |
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
42 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
43 |
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
|
44 |
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
|
45 |
|
d0ca211e1b0e
New HMAC token authentication module for Prosody.
JC Brand <jc@opkode.com>
parents:
diff
changeset
|
46 |
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
|
47 |
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
|
48 |
to `/usr/lib/prosody-modules/mod_auth_token/`). |