Add multi-factor authentication modules #15489

awarecan · 2018-07-16T13:36:44Z

Description:

Add multi-factor authentication support for new auth system.

Auth module

Multi-factor auth modules has been added to auth/modules folder.

~~totp is Time-based One Time Password module which compatible with Google Authenticator and Authy (not test yet). ~~ will be included in separate PR

insecure_example is a Example designed for demo and unit testing purpose, should not be used in any production system.

Multi-facot auth module can be used mixed-match with auth providers. After normal auth provider validate, if there are auth modules enabled for the specific user, the login flow will direct to auth module input form. Auth module use separated storage, can be hardening it in future.

Related issue (if applicable): fixes #

Pull request in developers.home-assistant.io with documentation (if applicable): home-assistant/developers.home-assistant#52

Example entry for `configuration.yaml` (if applicable):

# configuration.yaml
homeassistant:
  # Auth Provider
  auth_providers:
    - type: homeassistant
  auth_mfa_modules:
    - type: totp

Checklist:

The code change is tested and works locally.
Local tests pass with tox. Your PR cannot be merged unless tests pass

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated in developers.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

New dependencies have been added to the REQUIREMENTS variable (example).
New dependencies are only imported inside functions that use them (example).
New or updated dependencies have been added to requirements_all.txt by running script/gen_requirements_all.py.

If the code does not interact with devices:

Tests have been added to verify that the new code works.

houndci-bot · 2018-07-16T13:51:02Z

tests/scripts/test_auth.py

 from homeassistant.scripts import auth as script_auth
 from homeassistant.auth.providers import homeassistant as hass_auth

-from tests.common import register_auth_provider
+from tests.common import register_auth_provider, MockUser


'tests.common.MockUser' imported but unused

houndci-bot · 2018-07-16T13:51:02Z

tests/scripts/test_auth.py

@@ -3,10 +3,11 @@

 import pytest

+from homeassistant.auth.models import Credentials


'homeassistant.auth.models.Credentials' imported but unused

balloob · 2018-07-17T07:11:17Z

For architecture, if we need to resolve the flow result to credentials, we should just do that. We can't be making things up. Maybe we need a config flow that wraps the provider config flow instead of using inheritance. That way we can forward calls and then intercept the call to async_create_entry. But that too is a complicated solution. We should focus on the rest of the auth system before picking this up again.

awarecan · 2018-07-17T07:17:25Z

Sure, I am going to finish change user.mfa_modules design tomorrow, then I will put this PR on the shelf for a while.

The way mfa modules work, is that we persist in the user which mfa are enabled, and then we ask the mfa module to show a form. I feel like this violates the single source of truth. We should probably not store which mfa modules are enabled for a user. Instead:

MFA modules will get a method async_is_enabled_for(user)

We can add a method to auth manager to gather enabled MFA modules for a user. It then asks each MFA module.

balloob · 2018-07-17T07:24:16Z

I was thinking about that comment, and with credentials we do the exact opposite. We store the data that connects a user to an auth provider in the user. We should probably do that for MFA too. That way we can ask an MFA module: given this config and this value, is this ok? The only downside is if an MFA module wants to update the data 🤔

awarecan · 2018-07-17T08:02:38Z

That is current design:

in mfa data store:

{
    "data": {
        "users": [
            {
                "ota_secret": "some_secret",
                "user_id": "some_id"
            }
        ]
    },
    "key": "auth_module.totp",
    "version": 1
}

In auth

        "users": [
            {
                "id": "some_id",
                "is_active": true,
                "is_owner": true,
                "mfa_modules": ["totp"],
                "name": null,
                "system_generated": false
            }
        ]

awarecan · 2018-07-17T08:04:44Z

I can just delete mfa_modules from users since it is redundant, e.g. do not touch current auth data store in dev branch

balloob · 2018-07-17T17:35:09Z

Yeah, single source of truth 👍

awarecan · 2018-07-21T03:50:56Z

Rebase against dev

balloob · 2018-08-21T10:09:06Z

homeassistant/auth/__init__.py

-        """Result of a credential login flow."""
+            self, flow: LoginFlow, result: Dict[str, Any]) \
+            -> Dict[str, Any]:
+        """Return a user as result of login flow."""


We need to add a lot more documentation to this method . What is happening, when and why.

So I am slightly confused why we are even making changes for this method?

All auth provider login flows will create async_start_mfa(flow_result). The MFA flow will show more forms if necessary and eventually will pass the original flow result on if MFA has passed. That means that this method will not see any new data?

I changed design, now the auth provider (not the base class) will not know about mfa, they just call async_finish after validate credential. The _async_finish_login_flow will do the heave lift, if need mfa then change the result type to form by calling async_step_select_mfa_module

balloob · 2018-08-21T10:11:04Z

homeassistant/auth/mfa_modules/__init__.py

+        """Initialize an auth module."""
+        self.hass = hass
+        self.config = config
+        _LOGGER.debug('auth mfa module %s loaded.',


Constructors should never have side effects. Add this to auth_mfa_module_from_config

balloob · 2018-08-21T10:14:18Z

homeassistant/auth/providers/__init__.py

@@ -58,6 +61,11 @@ def name(self) -> str:
        """Return the name of the auth provider."""
        return self.config.get(CONF_NAME, self.DEFAULT_TITLE)

+    @property
+    def support_mfa(self) -> bool:


When would this not be the case?

For trusted networks auth provider

Ah interesting.

balloob · 2018-08-21T10:17:17Z

homeassistant/auth/providers/__init__.py

+        """Handle the first step of login flow.
+
+        Return self.async_show_form(step_id='init') if user_input == None.
+        Return await self.async_start_mfa(flow_result) if login init step pass.


Where is async_start_mfa defined?

I would expect async_start_mfa to not do anything if the context is type=link_user.

Aha, that is from old design, missed to update document. It should change to
Return await self.async_finish(flow_result) if login init step pass

awarecan · 2018-08-21T20:23:45Z

Rebase done, clean it up as much as possible, test should be able to pass, typing still need fix. And this PR is still 900+ lines need review 😄

houndci-bot · 2018-08-22T03:34:45Z

homeassistant/auth/providers/__init__.py

 from homeassistant.util import dt as dt_util
 from homeassistant.util.decorator import Registry

 from ..auth_store import AuthStore
-from ..models import Credentials, UserMeta
+from ..models import Credentials, User, UserMeta


'..models.User' imported but unused

houndci-bot · 2018-08-22T03:34:45Z

homeassistant/auth/providers/__init__.py

 import importlib
 import logging
 import types
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Callable


'typing.Callable' imported but unused

houndci-bot · 2018-08-22T06:08:23Z

homeassistant/auth/providers/__init__.py

@@ -1,4 +1,5 @@
 """Auth providers for Home Assistant."""
+from collections import OrderedDict


'collections.OrderedDict' imported but unused

balloob

🎉 🎉 🎉 🎉 🎉 🎉 🎉 🎉

* Get user after login flow finished * Add multi factor authentication support * Typings

awarecan requested a review from a team as a code owner July 16, 2018 13:36

homeassistant added cla-signed integration: config core labels Jul 16, 2018

ghost added the in progress label Jul 16, 2018

homeassistant added the cla-signed label Jul 16, 2018

houndci-bot reviewed Jul 16, 2018

View reviewed changes

awarecan force-pushed the auth-2fa-v2 branch from 54b17b5 to 6c255b2 Compare July 16, 2018 13:52

homeassistant added the cla-signed label Jul 16, 2018

awarecan force-pushed the auth-2fa-v2 branch from 6c255b2 to ec21f10 Compare July 17, 2018 06:19

homeassistant added the cla-signed label Jul 17, 2018

awarecan force-pushed the auth-2fa-v2 branch from 2acd72b to 658195c Compare July 18, 2018 17:39

homeassistant added the cla-signed label Jul 18, 2018

awarecan force-pushed the auth-2fa-v2 branch from 658195c to ef1a7af Compare July 18, 2018 17:44

homeassistant added the cla-signed label Jul 18, 2018

awarecan changed the title ~~WIP: [Recreated PR] Add multi-factor authentication plug-able modules~~ [Recreated PR] Add multi-factor authentication plug-able modules Jul 18, 2018

awarecan force-pushed the auth-2fa-v2 branch from 1543223 to 77788d2 Compare July 21, 2018 03:49

homeassistant added the cla-signed label Jul 21, 2018

awarecan force-pushed the auth-2fa-v2 branch from d33838f to 74726f7 Compare July 21, 2018 07:10

homeassistant added the cla-signed label Jul 21, 2018

awarecan force-pushed the auth-2fa-v2 branch from 74726f7 to 0698855 Compare August 17, 2018 02:24

homeassistant added the cla-signed label Aug 17, 2018

ghost assigned awarecan Aug 17, 2018

balloob reviewed Aug 21, 2018

View reviewed changes

Get user after login flow finished

665f79c

awarecan force-pushed the auth-2fa-v2 branch from a6f19b6 to fe8bcfd Compare August 21, 2018 19:33

homeassistant added the cla-signed label Aug 21, 2018

Add multi factor authentication support

25b8ef3

awarecan force-pushed the auth-2fa-v2 branch from fe8bcfd to 25b8ef3 Compare August 21, 2018 20:01

homeassistant added the cla-signed label Aug 21, 2018

houndci-bot reviewed Aug 22, 2018

View reviewed changes

awarecan force-pushed the auth-2fa-v2 branch from 9754beb to a1cf221 Compare August 22, 2018 03:41

homeassistant added the cla-signed label Aug 22, 2018

awarecan force-pushed the auth-2fa-v2 branch from a1cf221 to d8c7c2e Compare August 22, 2018 06:08

homeassistant added the cla-signed label Aug 22, 2018

houndci-bot reviewed Aug 22, 2018

View reviewed changes

Typings

c159810

awarecan force-pushed the auth-2fa-v2 branch from d8c7c2e to c159810 Compare August 22, 2018 06:22

homeassistant added the cla-signed label Aug 22, 2018

balloob approved these changes Aug 22, 2018

View reviewed changes

balloob merged commit 7e7f9bc into home-assistant:dev Aug 22, 2018

ghost removed the in progress label Aug 22, 2018

awarecan deleted the auth-2fa-v2 branch August 22, 2018 12:05

This was referenced Aug 22, 2018

Update auth document home-assistant/developers.home-assistant#52

Merged

Add Time-based Onetime Password Multi-factor Authentication Module #16129

Merged

Add TOTP MFA docs home-assistant/home-assistant.io#6089

Merged

balloob mentioned this pull request Aug 29, 2018

0.77 #16256

Merged

girlpunk pushed a commit to girlpunk/home-assistant that referenced this pull request Sep 4, 2018

Add multi-factor authentication modules (home-assistant#15489)

5e225ff

* Get user after login flow finished * Add multi factor authentication support * Typings

home-assistant locked and limited conversation to collaborators Dec 10, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add multi-factor authentication modules #15489

Add multi-factor authentication modules #15489

awarecan commented Jul 16, 2018 •

edited

Loading

houndci-bot Jul 16, 2018

houndci-bot Jul 16, 2018

balloob commented Jul 17, 2018

awarecan commented Jul 17, 2018

balloob commented Jul 17, 2018

awarecan commented Jul 17, 2018 •

edited

Loading

awarecan commented Jul 17, 2018 •

edited

Loading

balloob commented Jul 17, 2018

awarecan commented Jul 21, 2018

balloob Aug 21, 2018

balloob Aug 21, 2018

awarecan Aug 21, 2018

balloob Aug 21, 2018

balloob Aug 21, 2018

awarecan Aug 21, 2018

balloob Aug 21, 2018

balloob Aug 21, 2018

balloob Aug 21, 2018

awarecan Aug 21, 2018

awarecan commented Aug 21, 2018

houndci-bot Aug 22, 2018

houndci-bot Aug 22, 2018

houndci-bot Aug 22, 2018

balloob left a comment

		@@ -3,10 +3,11 @@

		import pytest

		from homeassistant.auth.models import Credentials

		@@ -1,4 +1,5 @@
		"""Auth providers for Home Assistant."""
		from collections import OrderedDict

Add multi-factor authentication modules #15489

Add multi-factor authentication modules #15489

Conversation

awarecan commented Jul 16, 2018 • edited Loading

Description:

Auth module

Example entry for configuration.yaml (if applicable):

Checklist:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

balloob commented Jul 17, 2018

awarecan commented Jul 17, 2018

balloob commented Jul 17, 2018

awarecan commented Jul 17, 2018 • edited Loading

awarecan commented Jul 17, 2018 • edited Loading

balloob commented Jul 17, 2018

awarecan commented Jul 21, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

awarecan commented Aug 21, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

balloob left a comment

Choose a reason for hiding this comment

awarecan commented Jul 16, 2018 •

edited

Loading

Example entry for `configuration.yaml` (if applicable):

awarecan commented Jul 17, 2018 •

edited

Loading

awarecan commented Jul 17, 2018 •

edited

Loading