Set up badge-based authentication

Confidential. Do not share. Trusted Tester only. Not publicly available.

For managed ChromeOS devices.

As an admin, you can integrate Chrome Enterprise with third-party identity providers (IdPs) to let users sign in to managed ChromeOS devices by tapping their badge, instead of having to enter their username and password.

What you need

To let third-party IdPs use badge authentication on ChromeOS devices, you need:

ChromeOS or ChromeOS Flex devices with Chrome OS version 119 or later.
Chrome Enterprise Upgrade for each device you want to manage.
Third-party IdP that supports badge-based authentication and administrator - level access to configure it.
Badge reader supported by ChromeOS and your chosen third-party IdP. View the list of ChromeOS-supported readers in Use smart cards on ChromeOS.
Organizational unit that contains Chrome OS devices and user accounts. If devices and user accounts don’t belong in organizational units that are configured in the same way, authentication fails.
Public Certificate Authority (CA) for the third-party IdP’s domain—On the sign-in screen, ChromeOS trusts the publicly trusted CAs for the web. View the list of currently trusted CA certificates.

How to

We recommend that first you apply settings to a small number of devices and users in a test organizational unit. Then, after you verify that devices are working correctly, you can apply them to your entire organization.

Note: Badge-based authentication into a user session with a super admin account is blocked. In general, super admins can't use SAML SSO for authentication.

Step 1: Install and configure Identity Card Connector extension

Sign in to your Google Admin console.
Sign in using your administrator account (does not end in @gmail.com).
In the Admin console, go to Menu DevicesChromeApps & extensionsUsers & browsers.
If you signed up for Chrome Browser Cloud Management, go to Menu Chrome browserApps & extensionsUsers & browsers.
(Optional) To apply the setting to a department or team, at the side, select an organizational unit. Show me how
Add Identity Card Connector extension:
1. Click AddAdd from Chrome Web Store.
2. In the search box, enter the extension ID agicampiiinkgdgceoknnjecpoamgigi and click Enter.
3. In the list, find and click Identity Card Connector extension.
4. Click Select.
Configure in-session policies. In the side panel that automatically opens when you install Identity Card Connector extension:
1. Under Installation policy, select Force install.
2. Under Policy for extensions, add or upload the extension policy using valid JSON format. Here is example JSON data that shows how to configure the extension for the main badge authentication flow. For details about the policies you can set, see table below.
3. Click Save.
Configure sign-in screen policies.
1. Open the Login screen for apps and extensions page.
2. (Optional) To apply the setting to a department or team, at the side, select an organizational unit. Show me how
3. In the list, find Identity Card Connector extension.
4. For Installation policy, select Installed.
5. In the list, click Identity Card Connector extension. A side panel opens where you can see additional details and configure policies.
6. Under Policy for extensions, add or upload the extension policy using valid JSON format. Here is example JSON data that shows how to configure the extension for the main badge authentication flow. For details about the policies you can set, see table below.
7. Click Save.

Step 2: Install and configure Smart Card Connector app

For Personal Computer Smart Card (PC/SC) readers, install and configure Smart Card Connector app.

Note: For non-PC/SC readers, you don’t need the Smart Card Connector app. Instead, contact Google Support to configure WebHID policies.

In the Admin console, go to Menu DevicesChromeApps & extensionsUsers & browsers.
If you signed up for Chrome Browser Cloud Management, go to Menu Chrome browserApps & extensionsUsers & browsers.
(Optional) To apply the setting to a department or team, at the side, select an organizational unit. Show me how
Add Smart Card Connector app:
1. Click AddAdd from Chrome Web Store.
2. In the search box, enter the app ID khpfeaanjngmcnplbdlpegiifgpfgdco and click Enter.
3. Find and click Smart Card Connector app.
4. Click Select.
Configure in-session policies. In the side panel that automatically opens when you install Smart Card Connector app:
1. Under Installation policy, select Force install.
2. Under Policy for extensions, add or upload the extension policy using valid JSON format. Here is example JSON data that allowlists Identity Card Connector extension to access Smart Card Connector app.
3. Click Save.
Configure sign-in screen policies:
1. Open the Login screen for apps and extensions page.
2. (Optional) To apply the setting to a department or team, at the side, select an organizational unit. Show me how
3. In the list, find Smart Card Connector app.
4. For Installation policy, click Installed.
5. In the list, click Smart Card Connector app. A side panel opens where you can see additional details and configure policies.
6. Under Policy for extensions, add or upload the extension policy using valid JSON format. Here is example JSON data that allowlists Identity Card Connector extension to access Smart Card Connector app.
7. Click Save.

Step 3: Configure SAML SSO for your device

For instructions, go to Configure SAML single sign-on for ChromeOS devices. For badge-based authentication, you don’t need to complete all of the steps that are described in the article:

Set up SSO—Required.
Test SSO—Optional.
Enable SAML SSO cookies—Optional, but recommended. Some users might also have other apps connected to their IdP. Configure SSO cookie behavior so that users are automatically signed into those apps when they use their badge to enter a user session.
Enable SAML SSO IdP Redirection—Optional, but recommended.
Control content on the sign-in and lock screens—Optional, but recommended.
Roll out SAML SSO for devices—Optional. Not required. If you tested SSO, then you’ll need to roll out SAML SSO for all devices. Otherwise, it’s not relevant.

Step 4: (Recommended) Configure device settings

Let devices go to sleep or shut down when they're idle

Setting this policy is a temporary measure to ensure that the IdP gets regularly reloaded until our upcoming IdP refresh policy is available.

In the Admin console, go to Menu DevicesChromeSettingsDevice settings.
(Optional) To apply the setting to a department or team, at the side, select an organizational unit. Show me how
Go to Power and shutdown.
Click Power management.
Select Allow device to sleep/shut down when idle on the sign-in screen.
Click Save.

Step 5: Set up device trust connector

Badge-based authentication requests sent from a ChromeOS device to an IdP server need to prove that they originate from a managed device in the correct domain.

To configure a new connector, you’ll need to get the following information from your chosen IdP:

Which of the available IdP providers to select
URLs patterns to allow
An IdP service account email

For a list of third-party IdPs with ChromeOS device trust connector support as well as details about how to set up device trust connectors, go to Manage Chrome Enterprise device trust connectors.

Troubleshoot

View in-session logs on ChromeOS device

On a ChromeOS device, open Chrome browser and go to chrome://inspect/#pages.
Find the page you want and click Inspect.
- chrome-extension://agicampiiinkgdgceoknnjecpoamgigi/offscreen/idp_document.html
On the Console tab, look for logs that come from the IdP. They are mixed with the logs from the extension. Filter by filename to more easily find the logs you’re looking for.

Identity Card Connector extension policies

Policy name	Description	Example
smartCardConnectorExtensionId	ID of the Smart Card Connector app that the Identity Card Connector extension uses to interact with PC/SC readers. Default value: ID of the production version of the Smart Card Connector app, khpfeaanjngmcnplbdlpegiifgpfgdco.	"smartCardConnectorExtensionId": { "Value": "khpfeaanjngmcnplbdlpegiifgpfgdco" }
inSessionOffscreenWebpageUrl	URL of the webpage that opens in an offscreen document to interact with the extension and use WebHID API. Left unset, no offscreen document opens.	"inSessionOffscreenWebpageUrl": { "Value": "https://my-idp.local/sso/login" }
loginScreenConnectUrlAllowlist	List of URLs that are allowed to establish a connection and communicate with the Identity Card Connector extension on the sign-in screen. URLs can end with a wildcard * symbol. There can be at most one active connection at once. Smart Card Connector app doesn’t need to be allowlisted because its connection is defined using smartCardConnectorExtensionId policy.	"loginScreenConnectUrlAllowlist": { "Value": [ "https://my-idp.local/sso/v1/login", "https://my-idp.local/sso/v2/login?*" ] }
inSessionConnectUrlAllowlist	List of URLs that are allowed to establish a connection and communicate with the Identity Card Connector extension in session, outside of an offscreen document. Webpages and extensions are allowed to connect. URLs can end with a wildcard * symbol. There can be at most one active connection at once. If the inSessionOffscreenWebpageUrl policy is configured, there will be an active connection with the webpage in the offscreen document and this policy will be ignored. Smart Card Connector app doesn’t have to be allowlisted because its connection is defined with smartCardConnectorExtensionId policy.	"inSessionConnectUrlAllowlist": { "Value": [ "https://my-idp.local/sso/login", "chrome-extension://imkicgecimgmikfilpaffhjkefncgabi/*" ] }
inSessionOffscreenRefreshMinutes	The number of minutes from when the webpage in an offscreen document is loaded until it has to be refreshed. The refresh happens automatically at the end of the refresh interval whenever the Identity Card Connector and the webpage won't communicate for at least 5 seconds. Default value: 0 minutes (policy is turned off)	"inSessionOffscreenRefreshMinutes": { "Value": 20 }

Policy name

Description

Example

smartCardConnectorExtensionId

ID of the Smart Card Connector app that the Identity Card Connector extension uses to interact with PC/SC readers.

Default value: ID of the production version of the Smart Card Connector app, khpfeaanjngmcnplbdlpegiifgpfgdco.

"smartCardConnectorExtensionId": {

"Value": "khpfeaanjngmcnplbdlpegiifgpfgdco"

}

inSessionOffscreenWebpageUrl

URL of the webpage that opens in an offscreen document to interact with the extension and use WebHID API.

Left unset, no offscreen document opens.

"inSessionOffscreenWebpageUrl": {

"Value": "https://my-idp.local/sso/login"

}

loginScreenConnectUrlAllowlist

List of URLs that are allowed to establish a connection and communicate with the Identity Card Connector extension on the sign-in screen.

URLs can end with a wildcard * symbol.

There can be at most one active connection at once.

Smart Card Connector app doesn’t need to be allowlisted because its connection is defined using smartCardConnectorExtensionId policy.

"loginScreenConnectUrlAllowlist": {

"Value": [

"https://my-idp.local/sso/v1/login",

"https://my-idp.local/sso/v2/login?*"

]

}

inSessionConnectUrlAllowlist

List of URLs that are allowed to establish a connection and communicate with the Identity Card Connector extension in session, outside of an offscreen document.

Webpages and extensions are allowed to connect.

URLs can end with a wildcard * symbol.

There can be at most one active connection at once.

If the inSessionOffscreenWebpageUrl policy is configured, there will be an active connection with the webpage in the offscreen document and this policy will be ignored.

Smart Card Connector app doesn’t have to be allowlisted because its connection is defined with smartCardConnectorExtensionId policy.

"inSessionConnectUrlAllowlist": {

"Value": [

"https://my-idp.local/sso/login",

"chrome-extension://imkicgecimgmikfilpaffhjkefncgabi/*"

]

}

inSessionOffscreenRefreshMinutes

The number of minutes from when the webpage in an offscreen document is loaded until it has to be refreshed.

The refresh happens automatically at the end of the refresh interval whenever the Identity Card Connector and the webpage won't communicate for at least 5 seconds.

Default value: 0 minutes (policy is turned off)

"inSessionOffscreenRefreshMinutes": {

"Value": 20

}

JSON examples

Here is an example JSON file that shows how to configure the extension for the main badge authentication flow.

{ "inSessionOffscreenWebpageUrl":{ "Value":"https://my-idp.local/sso/login" }, "loginScreenConnectUrlAllowlist":{ "Value":[ "https://my-idp.local/sso/v1/login", "https://my-idp.local/sso/v2/login?*" ] }, "smartCardConnectorExtensionId":{ "Value":"khpfeaanjngmcnplbdlpegiifgpfgdco" } }

Here is an example JSON file that allowlists Identity Card Connector extension to access Smart Card Connector app.

{ "force_allowed_client_app_ids":{ "Value":[ "agicampiiinkgdgceoknnjecpoamgigi" ] }, "scard_disconnect_fallback_client_app_ids":{ "Value":[ "agicampiiinkgdgceoknnjecpoamgigi" ] } }

Was this helpful?

How can we improve it?