-
-
Notifications
You must be signed in to change notification settings - Fork 8.3k
Add notify MFA module #6131
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add notify MFA module #6131
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -42,7 +42,7 @@ Below is a list of the currently available auth providers. | |
|
|
||
| [Time-based One-Time Password](https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm) is widely adopted in modern authencation system, it combines a secret key with the current timestamp using a cryptographic hash function to generate a one-time password. Whoever possessed the secret key will get same one-time password in certain time period. By verifying that password, Home Assistant knows the user have the right secrt key. | ||
|
|
||
| When trying to set up TOTP module, a QR code will show up. The user can scan it by an authenticator app, or set it up manually using the code showed in the UI. After setup, the user needs to input a six digit number generated in the autendicator app to verify the setup is good. If the verification keeps failing, you need to check whether the clock on Home Assistant is accurate. | ||
| When trying to set up TOTP module, a QR code will show up. The user can scan it by an authenticator app, or set it up manually using the code showed in the UI. After setup, the user needs to input a six digit number generated in the authenticator app to verify the setup is good. If the verification keeps failing, you need to check whether the clock on Home Assistant is accurate. | ||
|
|
||
| There are several authenticator apps on the market, we recommend either [Google Authenticator](https://support.google.com/accounts/answer/1066447) or [Authy](https://authy.com/). | ||
|
|
||
|
|
@@ -52,10 +52,48 @@ Please treat the secret key like a password, never expose it to others. | |
|
|
||
| By default, one TOTP multi-factor named "Authenticator app" will be auto loaded if no `auth_mfa_modules` configuration section defined in the `configuration.yaml` file. | ||
|
|
||
| By default one TOTP multi-factor auth module named "Authenticator app" will be auto loaded if no `auth_mfa_modules` config section defined in `configuration.yaml`. | ||
|
|
||
| Example of configuration: | ||
|
|
||
| ```yaml | ||
| homeassistant: | ||
| auth_mfa_modules: | ||
| - type: totp | ||
| ``` | ||
|
|
||
| ### {% linkable_title Notify mutli-factor authentication module %} | ||
|
|
||
| Notify MFA module using [notify component](https://www.home-assistant.io/components/notify/) to delivery a [HMAC-based One-Time Password](https://en.wikipedia.org/wiki/HMAC-based_One-time_Password_algorithm) to user configured target. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The notify MFA module uses notify component to deliver a HMAC-based One-Time Password to the user configured target. |
||
|
|
||
| User need first set up the MFA module by select one of the aviliable notify service. A 8 digit one-time password will be sent by this notify service, user need to input it to verify the setup. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The user needs to first set up the MFA module by selecting one of the available notify service. An 8 digit one-time password will be sent using this notify service, the user needs to input it to verify the setup. |
||
|
|
||
| During the login process, an 8 digit one-time password will be sent again, user need to input it to verify his/her identity. If the validation failed, a new one-time password will be sent again. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. During the login process, an 8 digit one-time password will be sent again, the user needs to input it to verify their identity. If the validation failed, a new one-time password will be sent. |
||
|
|
||
| <p class='note'> | ||
| Notify MFA module would not verify the one-time password deliveried success, so that if user cannot received the message due any reason, he/she may not be login again. Edit or remove `[your_config_dir]/.storage/auth_module.notify` can disable nofiy MFA module to resolve the issue. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The notify MFA module cannot verify the one-time password delivery success, so that if the user cannot received the message for any reason, they may not be login again. Edit or remove |
||
| </p> | ||
|
|
||
| Example of configuration | ||
|
|
||
| ```yaml | ||
| homeassistant: | ||
| auth_mfa_modules: | ||
| - type: notify | ||
| ``` | ||
|
|
||
| Optional configuration variables: | ||
|
|
||
| - **exclude** (*Optional*): The list of notify services you do not want to include in. | ||
| - **include** (*Optional*): The list of notify services you want to include in. | ||
| - **message** (*Optional*): The message template | ||
|
|
||
| ```yaml | ||
| # Example configure with message template | ||
| homeassistant: | ||
| auth_mfa_modules: | ||
| - type: totp | ||
| name: Authenticator app | ||
| - type: notify | ||
| message: 'I almost forget, to get into my clubhouse, you need to say {}' | ||
| ``` | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
By default one TOTP multi-factor auth module named "Authenticator app" will be auto loaded if no
auth_mfa_modulesconfig section is defined inconfiguration.yaml.