require authentication for notification action when flag is set

[dkarv]

Summary

Add the authenticationRequired flag for notification actions. It is already supported on iOS.
When enabled, the phone has to be unlocked to trigger a notification action. Useful e.g. for opening the door after the bell was ringed or other sensitive actions.
community request

Checklist

• New or updated tests have been added to cover the changes following the testing guidelines.
• The code follows the project's code style and best_practices.
• The changes have been thoroughly tested, and edge cases have been considered.
• Changes are backward compatible whenever feasible. Any breaking changes are documented in the changelog for users and/or in the code for developers depending on the relevance.

Link to pull request in documentation repositories

User Documentation: home-assistant/companion.home-assistant#1331

Any other notes

• I found no unit tests for the notifications, and most functions are private. No test is added because it would require building them from scratch for this small change.
• I only tested with local WebSocket notifications, not with Firebase. Do I need to whitelist the authenticationRequired key somewhere?

[home-assistant]

Hi @dkarv

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Extends notification action handling to propagate an authenticationRequired flag from websocket-received action payloads into built notification actions.

Changes:

• Flatten additional action fields (uri, behavior, authenticationRequired) when processing websocket data.
• Read authenticationRequired from notification action data and apply it via NotificationCompat.Action.Builder#setAuthenticationRequired.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
app/src/main/kotlin/io/homeassistant/companion/android/websocket/WebsocketManager.kt	Includes authenticationRequired (and consolidates flattening logic) when serializing action fields into a flattened map.
app/src/main/kotlin/io/homeassistant/companion/android/notifications/MessagingManager.kt	Reads the flattened authenticationRequired flag and sets it on built notification actions.

Stale

[jpelgrom]

Thanks for the suggestion. However, this doesn't map cleanly on the same pattern as iOS where it is a simple yes/no; the builder specifies

If this is true and the device is locked when the action is invoked, the OS will show the keyguard and require successful authentication before invoking the intent.

... so you won't be required to authenticate when the device is unlocked, even if you send true.

If this is false and the device is locked, the OS will decide whether authentication should be required.

... so you might still end up needing to authenticate if Android decides so, even when you send false.

[dkarv]

Thanks for your thoughts. I had another look to compare the behavior on both platforms:

... so you won't be required to authenticate when the device is unlocked, even if you send true.

This is the same behavior I saw on iOS. When the device is already unlocked, no further authentication is needed and the action is performed directly. According to the Apple documentation this is expected, it states The action can be performed only on an unlocked device.

... so you might still end up needing to authenticate if Android decides so, even when you send false.

I could not find any remark and never experienced this. So I checked in the AOSP code and it seems it just relies on that boolean we can pass: it is queried and passed down here and evaluated here

        if (isActivity || appRequestedAuth) {
            mActionClickLogger.logWaitingToCloseKeyguard(pendingIntent, actionIndex);
            final boolean afterKeyguardGone = mActivityIntentHelper
                    .wouldPendingLaunchResolverActivity(pendingIntent,
                            mLockscreenUserManager.getCurrentUserId());
            mActivityStarter.dismissKeyguardThenExecute(() -> {
                mActionClickLogger.logKeyguardGone(pendingIntent, actionIndex);

                try {
                    ActivityManager.getService().resumeAppSwitches();
                } catch (RemoteException e) {
                }

                boolean handled = defaultHandler.handleClick();

                // close the shade if it was open and maybe wait for activity start.
                return handled && mShadeController.closeShadeIfOpen();
            }, null, afterKeyguardGone);
            return true;
        } else {
            return defaultHandler.handleClick();
        }

Even if future Android version change it and require another authentication (e.g. when a device is unlocked for too long) I think this is only helping the goal of this flag and further improves security.

Happy to hear if I got something wrong. But in conclusion, I would argue the small potential difference in the future does not justify a separate flag for Android and iOS. It would need to be documented, users would need to put two flags into each notification definition in HA, and more.

I also checked again the backwards compatibility. If authenticationRequired is not given in the notification data, nothing changes for existing users.

[jpelgrom]

This is the same behavior I saw on iOS. When the device is already unlocked, no further authentication is needed and the action is performed directly. According to the Apple documentation this is expected, it states The action can be performed only on an unlocked device.

In that case I think the companion app documentation should also be updated to reflect that, right now it suggests otherwise.

[dkarv]

In that case I think the companion app documentation should also be updated to reflect that, right now it suggests otherwise.

Makes sense, I changed the documentation in the linked PR:

| authenticationRequired | Optional. If true, the device needs to be unlocked before the action is triggered. | BETA on Android. Requires at least Android 12. |

[jpelgrom]

Thanks for updating the documentation. In that case as behavior matches I see no objections.

I only tested with local WebSocket notifications, not with Firebase. Do I need to whitelist the authenticationRequired key somewhere?

You need to add the key to the list of keys that are passed to Android like here: https://github.com/home-assistant/mobile-apps-fcm-push/blob/main/functions/android.js#L27-L29. If you submit a PR we'll merge it alongside all the other ones and it will immediately start working with FCM.

[jpelgrom]

Could you also add a short line for this change to the in-app changelog like "Added support for ..."?

[dkarv]

You need to add the key to the list of keys that are passed to Android like here: https://github.com/home-assistant/mobile-apps-fcm-push/blob/main/functions/android.js#L27-L29. If you submit a PR we'll merge it alongside all the other ones and it will immediately start working with FCM.

Created the PR: home-assistant/mobile-apps-fcm-push#306

Could you also add a short line for this change to the in-app changelog like "Added support for ..."?

Also done, hope I added it the correct way.

Thanks overall for your suggestions and help to bring this to live, appreciate it.