Introduction

Purpose

CloudStack lacks a native 2FA authentication mechanism wherein users would be asked required to put in some code or do some kind of challenge as part of authentication. 2FA or two-factor authentication is a two-step authentication wherein a user needs to first enter their credentials and then be asked some kind of token as 2nd step. A user is only allowed access to CloudStack when both credentials and 2FA token are correct.

References

• A PoC was created as part of CCC21 hackathon: https://github.com/apache/cloudstack/pull/5683

Document History

Glossary

Feature Specifications

• Implement a general-purpose 2FA framework that works on the principle of a secondary token to be provided by the user.
  • Add an optional token API parameter as part of the login API. This is checked/enforced by backend depending on if 2FA is enabled and enforced for a user-account.
• The framework should allow plugins that can be enabled granularly on user/account level, or enforced (both 2FA enabled and 2fA plugin) at global/domain level by the root admin.
• Implement two general-purpose 2FA plugins:
  
  • Google Authenticator: token to be generated by Google or other TOTP (time-based OTP) 2FA authenticator apps
  • Static PIN: user sets up this 4 or 6 digit PIN
• Future: 
  • Operators use the 2FA framework to implement custom plugins - say using sms or email OTP
• The 2FA plugins will have both backend and UI components/counterparts
• Explore if 2FA can be supported by cmk as well (at least with username/password login)

Use cases

Allow an extra layer of security for users and environments that want to user or enforce 2FA.

Architecture and Design description

• Implement the feature in framework-plugin model. The feature is enabled by default.
• Allow users to select 2FA plugin/option in UI when it's not strictly enforced by root admin.
• Allow creation of new user/accounts with 2FA enabled/enforced (say on first login?).
• 2FA to be linked with a user (not account).
• Workflow:
  • Setup:
    • Root admin can enforce 2fA with specific plugin on global/domain level
    • Users click on button to enable 2FA, if root admin allows permission they can select plugin too otherwise they get whatever the admin has configured.
    • Depending on the plugin, say the TOTP/authenticator app, they're show forms/views to setup 2FA.
    • Once confirmed, 2fA is enabled and enforced for the user.
    • If 2FA is enforced by admin, then for a user who hasn't configured it - a form opens up upon log-in to remind the user to configure and enable it.
  • Auth:
    • User enters username, password, domain
    • User is asked for 2FA token if 2FA is enforced and enabled for the user; for TOTP and PIN based plugins they can be sent to backend API directly as part of the login request
    • Upon success they're taken to the url/dashboard, otherwise the session is invalidated with clear message show