PWA App - How can I check that app is running in kiosk mode? [ChromeOS]

[Rushabh Shah]

I had a Chromeos app and it was working fine. As Google now deprecated chromeos apps we are migrating to pwa app.

We were using the below code to check if the app is in kiosk mode and apply our logic only if it is in kiosk else we show the error dialogue.

chrome.app.runtime.onLaunched.addListener(function(launchData) { launchData.isKioskSession; //true or false });

I could not find any similar way to do that using the PWA app in chromeOS for chrome books.

Here is the official doc for launch data: https://developer.chrome.com/docs/extensions/reference/app_runtime/

[dragon788]

Not sure if any of these links have more details on that specific scenario, they are about writing apps specifically for kiosk mode.

I'm not sure how you would determine if a user was trying to access it without being in kiosk mode, how does that scenario come about, shouldn't the app/site only be pushed to devices in managed guest or kiosk mode?

Create and deploy Chrome kiosk apps - Google Help https://g.co/kgs/gMMDKH

Manage Chrome kiosk app settings - Chrome Enterprise and Education Help - Google Help https://g.co/kgs/WuWJQy

Kiosk apps on ChromeOS https://chromeos.dev/en/kiosk

https://youtu.be/gQ6arLknnMY

--
--
Chromium OS Discussion mailing list: chromium-...@chromium.org
View archives, change email options, or unsubscribe:
https://groups.google.com/a/chromium.org/group/chromium-os-discuss
---
To unsubscribe from this group and stop receiving emails from it, send an email to chromium-os-dis...@chromium.org.

[Rushabh Shah]

Hi,

Thank you very much for responding!

I pointed to the links in your response. My problem is that I have a PWA app that I would like to run in kiosk mode. Now, any user may access the same link by opening it in the browser of any other device or unmanaged Chromebook device. Previously, I handled it by utilising the chrome.app.runtime API launchdata.kiosksession. And such capability should only be available to kiosk users in chrome app. 

chrome.app.runtime.onLaunched.addListener(function(launchData) { launchData.isKioskSession; //true or false });

When transitioning to a PWA app, I cannot discover any equivalent API for web apps. There is a chrome.runtime api, but no kiosk session check.

I hope you understand my concern.

[dragon788]

It's crazy how hard they make it to figure that out now.

From what I can tell, what you would need to do is create a companion extension to be pushed through the Google admin console specifically ONLY on the devices in kiosk mode and then your PWA can query whether that extension is installed and if it's not then present the error message about it not being a device allowed to use the site. I don't know that the ability to interact with the platform keys API would help identify kiosk mode, but building an extension that utilizes that permission would ensure that it could only be installed on enrolled or kiosk mode devices, and those extensions need to be forced installed in order to actually get the permissions, meaning a Google workspace admin has to enable it in the policies/portal and a user logged in on an enrolled device installing the extension themselves wouldn't satisfy the criteria.

You can also build a companion extension that pairs with your PWA in kiosk mode. Doing so lets you take advantage of Chrome APIs⁠ (such as chrome.runtime) and advanced capabilities, like configuring display settings, controlling connected audio, and rebooting devices, that kiosk and enterprise extensions can be enabled to do.

It really looks like Google should add another login state type in addition to not logged in, OOBE, and in session, for in kiosk session.

https://developer.chrome.com/docs/extensions/reference/loginState/

https://stackoverflow.com/a/74710892

[Rushabh Shah]

Hi @dragon788

First of all, thank you so much for your response! It really lightened some hope for resolution.

From what I can tell, what you would need to do is create a companion extension to be pushed through the Google admin console specifically ONLY on the devices in kiosk mode, and then your PWA can query whether that extension is installed and if it's not then present the error message about it not being a device allowed to use the site. 

- We are working on this approach and are able to find and established communication between the extension and pwa app. Can we just push the extension only on managed Chromebook devices for kiosk mode? 

Would be very helpful if you can link us to the document or blog containing information about it.

Again thank you so much for all of your help!

[dragon788]

Yeah, you can push an extension similarly to how you push the application, it is in the Google Admin settings for Chrome under the kiosk settings.

https://support.google.com/chrome/a/answer/9273974?hl=en

https://chromeos.dev/en/kiosk/connecting-an-extension-from-a-kiosk-pwa

[Joyce Toh]

Hi, and thanks for kicking off this discussion! dragon788 was definitely on the right track with the idea to have a companion extension. But to make sure you have a more secure and stable solution, we've just recently launched a new kiosk detection capability via the Chrome Verified Access API . Unfortunately, we're still working on updating the documentation there but in the meantime, please take a look at the current documentation for Chrome Verified Access API, an existing API and mechanism to ensure API calls aren't spoofed and you're able to securely get the identity and other info about the client device. For kiosk detection, when calling the challenge.verify method, you should set expectedIdentity to 'KIOSK_MODE'. If successful, you'll see a response of an empty string or empty json, meaning the device is in kiosk mode. Else, you'll see a 404 code in the response body with error "Requested entity was not found."

For verified access, you will need to have a companion Chrome extension and a backend service, in addition to your PWA kiosk app. And like you shared, the chromeos.dev article has details on connecting an extension from a kiosk app. We've also got a code sample if that's helpful. 

When the official API documentation is updated, I'll post an update to this thread. 

[Rushabh Shah]

Awesome information! Thank you so much. I will definitely look into it.

[Rushabh Shah]

Hello,

We've been following the approach you recommended, which involves utilizing the https://verifiedaccess.googleapis.com/v2/challenge API to get a challenge.

You can find detailed information in the documentation link: https://developers.google.com/chrome/verified-access/developer-guide.

During our attempts to access the API with the required payload, we encountered a 404 Not Found error. By researching further, we found the possibility of using the https://verifiedaccess.googleapis.com/v2/challenge:generate API to obtain a challenge. By providing the required payload, we managed to successfully retrieve a response structured as follows:

V2 version response:
{
"challenge": "// Response string"
}

Our current challenge lies in the subsequent stage, where we're trying to encode the challenge response. This process requires the usage of the "data" and "signature" parameters from the challenge response, as illustrated below:

Expected Response to encode a challenge:
{
"challenge": {
"data": "",
"signature": ""
}
}

Could someone please guide us on the process of encoding the challenge using the response received from the v2/challenge:generate API? What specific values should be supplied for the "data" and "signature" parameters?

For more clarity regarding the encoding procedure for the challenge, please consult the provided Helper code to encode the challenge. in the document.

Thank you!

[Joyce Toh]

Hi Rushabh,

Thanks for sharing the details around your approach and catching that mistake in our documentation. We'll be sure to fix up the documentation to reflect the new v2 API accurately.

As you discovered, the v2 response only returns the challenge string and doesn't have the data and signature fields. So you actually won't need the helper encode to encode the challenge anymore. The challenge string that gets returned will already be encoded. You can then use it to generate a challenge response (next step in the guide) using chrome.enterprise.platformKeys.challengeUserKey (I forgot to mention last time that for kiosk mode detection, you''ll need user key).

Hope this helps!

Best,

Joyce

[Rushabh Shah]

@Joyce

Hello,

In the second step to generate a challenge-response, we require chrome.enterprise.platformKeys.challengeUserKey. 

Specifically, I'm encountering an error related to chrome.enterprise.platformKeys.challengeUserKey: "Uncaught TypeError: Cannot read properties of undefined (reading 'platformKeys')".

Could you kindly tell us how to enable that API through the admin console? So that the organizational unit can have access to it. We dig the document linked below but we could not find a way to create or enable that API.

Fails if this operation has not explicitly been enabled for the caller by enterprise user policy.

https://developer.chrome.com/docs/extensions/reference/enterprise_platformKeys/

Just so you know, once it's enabled, we'll try to push the extension to a managed Chrome device to test it.

[Joyce Toh]

Hi Rushabh,

So the reason you're seeing is because the platformKeys API is only available for extensions pre-installed by policy (there's a note about this at the top of the API reference). So you'll need to push the extension to a managed Chrome device or user to test it. 

You can follow step 1 and 3 in this guide to install your kiosk and companion extension in the admin console. If you'd like to test outside of kiosk mode first, you can also just add your extension for user mode (obviously kiosk detection would fail but you can still validate that the API works).

[MANISHA K RAI]

Hi Joyce Toh @Joyce,

We too have followed the document mentioned in the above discussion and we  encounter "Uncaught TypeError: Cannot read properties of undefined (reading 'platformKeys')" at the second step. And we use enterprise.platformKeys.challengeMachineKey to generate the challenge response. However we would first test the extension working, by installing it for the user mode as mentioned by you. While at it what should be the type of app or extension ( User & browsers OR kiosk) when installing the extension for the testing purpose. Our purpose in real is to use this extension as a companion extension for the KIOSK mode detection.

Thanks in advance,
Manisha K Rai

[Joyce Toh]

Hi Manisha,

How are you installing your extension in user mode. Note that the chrome.enterprise.platformKeys API is only available for extensions pre-installed by policy. You'll see that error likely because you're not on a managed device and there's no install policy for your extension. You'll force-install the extension in the Google Admin Console under the "User & browsers" tab to test in user mode. To test in kiosk mode as a companion extension, you'll first add your app under "Kiosk" and then there's an option to add a companion extension to your kiosk app. Hope that helps!

Best,

Joyce

[MANISHA K RAI]

Hi Joyce @Joyce

Thank you for letting me know that. 
I had a doubt with regards to using challengeMachineKey or challengeUserKey for KIOSK mode detection. The chrome book that we have is assigned to a domain and I will not be logged in as any user. We are thinking of the following approach - On trying to launching my PWA KIOSK app from the app section I need the companion extension to be triggerred and return the results for KIOSK detection. 
I have followed the steps mentioned in the guide, but when using enterprise platform API I am unsure  about using challengeMachineKey or challengeUserKey since both of these take the same input parameters. And also I had seen in the above converstaions that you suggested using userKey , but I dont really understand the difference as I will not be logged as any user when trying to launch the app.

Thanks in advance,
Manisha K Rai

.

[Joyce Toh]

Hi Manisha,

You should use challengeUserKey as that's how kiosk detection was implemented. It seems counter-intuitive, but you can think of kiosk as the "user" in this scenario. Whereas a machine key is used to verify the device is a ChromeOS device and is managed but doesn't attest to the mode of the device (user, managed guest, kiosk).

[MANISHA K RAI]

Hi Joyce @Joyce

Thank you. Also I have installed the extension via policy and on a managed chrome book. The chrome.enterprise.platformKeys.challengeUserKey(

challenge, true, ChallengeCallback) sends a undefined response to the ChallengeCallback function that we have defined in our extension code. We have also included 'enterprise.platformKeys' under permissions in manifest file but the extension errors out saying 'Unchecked runtime.lastError: The extension does not have permission to call this function'. Is there anything else that we are missing in this context that needs to be specifically addressed for the enterprise.platformKeys? Due to this we are unable to proceed with the step 3( https://verifiedaccess.googleapis.com/v2/challenge:verify?key=' + apiKey;) mentioned in the guide. Thanks in advance, Manisha K Rai

[Joyce Toh]

In the admin console where you have the extension install policy, make sure to enable the "Allow enterprise challenge" setting under Certificate Management. You will see that error if your extension ID is not in the AttestationExtensionAllowlist which you can see at chrome://policy.

[MANISHA K RAI]

Hi Joyce @Joyce,

In this https://developer.chrome.com/docs/extensions/reference/enterprise_platformKeys/#method-challengeUserKey document its been told to use challengeKey instead of challengeUserKey as this has been deprecated. Reason for asking is, I use chrome.enterprise.platformKeys.challengeUserKey(verifiedChallengebuffer,true,ChallengeCallback) ,and this function calls the ChallengeCallback function with 'undefined' response thus resulting in Unchecked runtime.lastError: failed to sign the challenge.
Extension is running inside a managed/enterprise chromebook. It is unclear to me why do we get the 'undefined' response. Is there anything else that needs to be explicitly done to resolve this error apart from the steps mentioned in this ( https://developers.google.com/chrome/verified-access/developer-guide) document?

Thanks in advance,
Manisha K Rai

[MANISHA K RAI]

Hi @Joyce

After trying different approaches we still get 'undefined' response from chrome.enterprise.platformKeys.challengeUserKey as well as chrome.enterprise.platformKeys.challengKey which gets passed to the callback function as the input. Any suggestions on how this can be fixed? @Joyce

Thanks,

Manisha K Rai

[Rushabh Shah]

We have created an extension and installed it on chromeOS by force install police by enterprise admin.

We are calling API chrome.enterprise.platformKeys.challengeUserKey and all the functions mentioned in the developer guide for example, ab2base64str, ChallengeCallback, decodestr2ab, But it's returning an empty string. could you please guide us if anything needs to be added or removed from the functions we are using?

Also, we are not able to debug the extension that is pushed via the admin console using force install on Chrome Book as the inspect element is not allowed in that extension. That's the roadblock for us now. Please let us know if we need to enable a policy for it.

Plugin link: https://chromewebstore.google.com/detail/chrome-verified-access-ap/deiecalonjgmdbgblmpkkghicimncfle?hl=en

[MANISHA K RAI]

Hi,

Will there be any issue with the working of the companion extension when installed by the super admin and not by the enterprise admin?

Thanks in advance,
Manisha K Rai

[MANISHA K RAI]

Hi Joyce Toh, dragon788,

Created a extension and installed it under users and browsers for the testing purpose. We do get the response for -
 enterprise.platformKeys.challengeKey with scope being USER. On passing this response to the challenge.verify with expectedIdentity set to KIOSK_MODE this is the response that we get 
:
"The caller does not have permission"
status
:
"PERMISSION_DENIED"
As per the document it must be 'empty string' when installed as a companion extension on PWA otheriwse under testing it should say - 'Requested entity was not found'. But we get - 'The caller does not have permission' instead of 'Requested entity was not found'. We have the necessary permissions and we even pass the api key for the verify API, so i am not sure why do we now get 403 permission denied on the challenge.verify API when the other two APIs worked perfectly.
This will be the last step for testing this extension under Users and browsers. Kindly help needed here. Much appreciated
@Joyce @dragon788

Thanks in advance,
Manisha K Rai

[MANISHA K RAI]

In continuation to the above, This cannot be a permission issue as the generate and enterprise APIs work fine. Could this any issue with V2 verify API?

[Rushabh Shah]

Hi @Joyce Toh,

+ Following up. 

"We have created an extension and installed it on chromeOS by force install police by enterprise admin.

We are calling API chrome.enterprise.platformKeys.challengeUserKey and all the functions mentioned in the developer guide for example, ab2base64str, ChallengeCallback, decodestr2ab, But it's returning an empty string. could you please guide us if anything needs to be added or removed from the functions we are using?

Also, we are not able to debug the extension that is pushed via the admin console using force install on Chrome Book as the inspect element is not allowed in that extension. That's the roadblock for us now. Please let us know if we need to enable a policy for it.

Plugin link: https://chromewebstore.google.com/detail/chrome-verified-access-ap/deiecalonjgmdbgblmpkkghicimncfle?hl=en"

[Raad Altaie]

Why do you make it so complicated to determine if the app is in kiosk mode or not? Why do I have to solve a quantum challenge via remote API to know if my PWA is running in kiosk?

Can't you just add a simple boolean flag to the navigator, something like navigator.kioskEnabled?

What's the security risk if someone knew the app is running in kiosk?

I know I sound frustrated because I spent a week trying to solve this issue which shouldn't have existed from the beginning.

[Joyce Toh]

Hi Manisha,

I think the root cause of your issue is that you haven't configured a service account to be used with the Verified Access API. First "Create a service account" and then it must be enabled access to your managed Chromebook device. Here's that step copied from "Enroll a managed Chromebook device"

4. Policies are configured to enable Verified Access, allowlist the Chrome extension, and grant access to the API for the service account representing the network service (see the Google Admin console Help documentation).

Then you'll use the service account private key as the credential to call the challenge.verify method. (Here's how to use the service account credentials for Node.js as an example if you're using the Google API Nodejs client library).

Best,

Joyce

[Joyce Toh]

Hi Raad,

Thank you for sharing your feedback and I can understand your frustration. The security risk isn't with someone knowing that the app is running in kiosk mode. But rather, a boolean field like you're proposing can very trivially be spoofed by a user from outside of kiosk mode (via the Chrome Dev tools console), thereby rendering the locked down guarantee of kiosk useless if the app cannot accurately confirm their app is in fact running in kiosk mode. I hope this sheds some light on why we're using the Verified Access API for kiosk detection as it's a hardware-backed guarantee. 

Please do share any gaps in our documentation you've seen or issues you've run into so we can improve our documentation for you and other developers. Thank you!

Best,

Joyce

[Raad Altaie]

Thank you, Joyce, for your reply!

Why not let the companion extension tell the PWA if kiosk mode is enabled, since it's already approved by the admin and installed via the admin portal by the super admin?

I really don't understand how the product manager thought that going through the following steps to know if your PWA is in kiosk mode is a great idea, and the developers will love it:

1. Create a Google account.
2. Create a Google Cloud project and set up billing.
3. Enable the Verified Access API and create a service account.
4. Save the secret account on the backend.
5. Create a backend Custom API Server to verify the challenge response server.
6. Request a challenge from the Google API.
7. Call the local chrome.enterprise.platformKey API to generate a challenge response.
8. Send the expected identity and challenge response to your custom API.
9. On top of that, develop a Chrome extension that can talk to the Chrome Enterprise API.

Then, we will be able to tell if your app is running in kiosk mode or not. Honestly, I would rather be hit by a bus than do all of that.

Hopefully, this will be fixed someday.

[Patrick McManamon]

Hi, Joyce

I've been trying to implement the verified access API for some time now. There seems to be very little public resources outside of the provided google guides so it proves very hard to debug any issues. Anyway, I have an issue specifically with the  /v2/challenge:verify endpoint where it returns a code 200 but empty JSON response for a user verification but a code 403 and 'The caller does not have permission' error message. This is strange as a I have granted the service account full access to both device and user data, are using accounts and devices enrolled onto a single domain and have force installed the extension. I have also confirmed that authenticated account is infact the correct service account on the correct project with the correct oauth scopes. I would really appreciate any input as I have hit a brick wall here and there seems to be no support.

Many thanks,
Patrick