Skip to content

Latest commit

 

History

History
86 lines (57 loc) · 3.27 KB

second_factor_auth.md

File metadata and controls

86 lines (57 loc) · 3.27 KB
Raw

Second Factor Authentication (2FA)

According with wikipedia Two-factor authentication (also known as 2FA) is a type (subset) of multi-factor authentication. It is a method of confirming a user's claimed identity by utilizing a combination of two different factors: 1) something they know, 2) something they have, or 3) something they are.

This feature provides 2FA for OpenStack Keystone based on email.

2FA feature extends token data returned from keystone to user by "POST /v3/auth/tokens", including new fields in 'extra' dictionary of 'token':

 "extras": {
     ...
     "sndfa": true
     "sndfa_email": true
     ...
     },

When Keystone is expecting that user accepts 2FA challenge, the following error response is obtained:

{"error": {"message": "Expecting Second Factor Authentication, email was sent. Please check it and click in provided link.", "code": 401, "title": "Unauthorized"}}

Configuration

Specific options at /etc/keystone/keystone.conf

[spassword]
sndfa=true
sndfa_time_window=24
sndfa_endpoint='localhost:5001'
  • sndfa is a boolean which enables (true) or disables (false) if Second Factor Authentication feature is available in Keystone instance.
  • sndfa_time_window indicates the time in hours in which Second Factor Authentication performed by an user is still valid before ask another new one.
  • sndfa_endpoint is the endpoint used in links sent by email to users to check email address and sndfa changes (i.e. localhost:5001, https://localhost/idm, etc.)

In order to work with Second Factor Authentication feature spassword needs a proper smtp configuration; make sure that you provide one.

[spassword]
smtp_server=localhost
smtp_port=587
smtp_tls=true
smtp_user='[email protected]'
smtp_password='yourpassword'
smtp_from='smtpuser'

API

Second Factor authentication introduces new methods:

  • Ask to check current user email. A code will be sent to user to that email.

    GET /v3/users/<user_id>/checkemail

    This call uses a x-auth-token associated to <user_id> user.

  • Check a code to validate user email. The code was received by user in his email.

    GET /v3/users/<user_id>/checkemail/<code>

    This call does not need a x-auth-token. Tipically is done by click in an email link.

  • Modify configuration for second factor authentication for a user, allowing enable or disable it.

    POST /v3/users/<user_id>/sndfa

    The payload for this request is either {"enable":true} to enable second factor or {"enable":false} to disable it. This call uses a x-auth-token associated to <user_id> user.

  • Check a second factor authentication code to allow user authentication. Code is just valid during sndfa_time_window.

    GET /v3/users/<user_id>/sndfa/<code>

    This call does not need a x-auth-token. Tipically is done by click in an email link.

  • Force to recover a user passsword.

    GET /v3/users/<user_id>/recover_password

    This call does not need a x-auth-token

Note that in order to use the POST /v3/users/<user_id>/sndfa operation first the user email must be validad. Thus, the GET /v3/users/<user_id>/checkemail (and later email validation with GET /v3/users/<user_id>/checkemail/<code>) call must be done before.