ceph/doc/radosgw/mfa.rst

   1 .. _rgw_mfa:
   2
   3 ==========================================
   4 RGW Support for Multifactor Authentication
   5 ==========================================
   6
   7 .. versionadded:: Mimic
   8
   9 The S3 multifactor authentication (MFA) feature allows
  10 users to require the use of one-time password when removing
  11 objects on certain buckets. The buckets need to be configured
  12 with versioning and MFA enabled which can be done through
  13 the S3 api.
  14
  15 Time-based one time password tokens can be assigned to a user
  16 through radosgw-admin. Each token has a secret seed, and a serial
  17 id that is assigned to it. Tokens are added to the user, can
  18 be listedm removed, and can also be re-synchronized.
  19
  20 Multisite
  21 =========
  22
  23 While the MFA IDs are set on the user's metadata, the
  24 actual MFA one time password configuration resides in the local zone's
  25 osds. Therefore, in a multi-site environment it is advisable to use
  26 different tokens for different zones.
  27
  28
  29 Terminology
  30 =============
  31
  32 -``TOTP``: Time-based One Time Password
  33
  34 -``token serial``: a string that represents the ID of a TOTP token
  35
  36 -``token seed``: the secret seed that is used to calculate the TOTP
  37
  38 -``totp seconds``: the time resolution that is being used for TOTP generation
  39
  40 -``totp window``: the number of TOTP tokens that are checked before and after the current token when validating token
  41
  42 -``totp pin``: the valid value of a TOTP token at a certain time
  43
  44
  45 Admin commands
  46 ==============
  47
  48 Create a new MFA TOTP token
  49 ------------------------------------
  50
  51 ::
  52
  53    # radosgw-admin mfa create --uid=<user-id> \
  54                               --totp-serial=<serial> \
  55                               --totp-seed=<seed> \
  56                               [ --totp-seed-type=<hex|base32> ] \
  57                               [ --totp-seconds=<num-seconds> ] \
  58                               [ --totp-window=<twindow> ]
  59
  60 List MFA TOTP tokens
  61 ---------------------
  62
  63 ::
  64
  65    # radosgw-admin mfa list --uid=<user-id>
  66
  67
  68 Show MFA TOTP token
  69 ------------------------------------
  70
  71 ::
  72
  73    # radosgw-admin mfa get --uid=<user-id> --totp-serial=<serial>
  74
  75
  76 Delete MFA TOTP token
  77 ------------------------
  78
  79 ::
  80
  81    # radosgw-admin mfa remove --uid=<user-id> --totp-serial=<serial>
  82
  83
  84 Check MFA TOTP token
  85 --------------------------------
  86
  87 Test a TOTP token pin, needed for validating that TOTP functions correctly. ::
  88
  89    # radosgw-admin mfa check --uid=<user-id> --totp-serial=<serial> \
  90                              --totp-pin=<pin>
  91
  92
  93 Re-sync MFA TOTP token
  94 --------------------------------
  95
  96 In order to re-sync the TOTP token (in case of time skew). This requires
  97 feeding two consecutive pins: the previous pin, and the current pin. ::
  98
  99    # radosgw-admin mfa resync --uid=<user-id> --totp-serial=<serial> \
 100                               --totp-pin=<prev-pin> --totp=pin=<current-pin>
 101
 102