summaryrefslogtreecommitdiffstats
path: root/doc/radosgw/mfa.rst
blob: 416f23af106b36ce352d2d48cc86c66e4a0b2ede (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
.. _rgw_mfa:

==========================================
RGW Support for Multifactor Authentication
==========================================

.. versionadded:: Mimic

The S3 multifactor authentication (MFA) feature allows
users to require the use of one-time password when removing
objects on certain buckets. The buckets need to be configured
with versioning and MFA enabled which can be done through
the S3 api.

Time-based one time password tokens can be assigned to a user
through radosgw-admin. Each token has a secret seed, and a serial
id that is assigned to it. Tokens are added to the user, can
be listed, removed, and can also be re-synchronized.

Multisite
=========

While the MFA IDs are set on the user's metadata, the
actual MFA one time password configuration resides in the local zone's
osds. Therefore, in a multi-site environment it is advisable to use
different tokens for different zones.


Terminology
=============

-``TOTP``: Time-based One Time Password

-``token serial``: a string that represents the ID of a TOTP token

-``token seed``: the secret seed that is used to calculate the TOTP

-``totp seconds``: the time resolution that is being used for TOTP generation

-``totp window``: the number of TOTP tokens that are checked before and after the current token when validating token

-``totp pin``: the valid value of a TOTP token at a certain time


Admin commands
==============

Create a new MFA TOTP token
------------------------------------

::

   # radosgw-admin mfa create --uid=<user-id> \
                              --totp-serial=<serial> \
                              --totp-seed=<seed> \
                              [ --totp-seed-type=<hex|base32> ] \
                              [ --totp-seconds=<num-seconds> ] \
                              [ --totp-window=<twindow> ]

List MFA TOTP tokens
---------------------

::

   # radosgw-admin mfa list --uid=<user-id>


Show MFA TOTP token
------------------------------------

::

   # radosgw-admin mfa get --uid=<user-id> --totp-serial=<serial>


Delete MFA TOTP token
------------------------

::

   # radosgw-admin mfa remove --uid=<user-id> --totp-serial=<serial>


Check MFA TOTP token
--------------------------------

Test a TOTP token pin, needed for validating that TOTP functions correctly. ::

   # radosgw-admin mfa check --uid=<user-id> --totp-serial=<serial> \
                             --totp-pin=<pin>


Re-sync MFA TOTP token
--------------------------------

In order to re-sync the TOTP token (in case of time skew). This requires
feeding two consecutive pins: the previous pin, and the current pin. ::

   # radosgw-admin mfa resync --uid=<user-id> --totp-serial=<serial> \
                              --totp-pin=<prev-pin> --totp=pin=<current-pin>