Configure SAML single sign-on for ChromeOS devices

Security Assertion Markup Language (SAML) single sign-on (SSO) support for ChromeOS devices allows users to sign in to a device with the same authentication mechanisms that you use within the rest of your organization. Their passwords can remain within your organization's Identity Provider (IdP). Signing in is very similar to signing in to a Google Workspace account from a browser via SAML SSO. However, because a user is signing in to a device, there are several additional considerations.

For more details, see Set up single sign-on for managed Google Accounts using third-party Identity providers.

Requirements

• ChromeOS device running version 36 or higher
• Domain configured for SAML SSO for Google Workspace
• SAML URL using HTTPS not HTTP
• ChromeOS licenses for your devices

Step 1:

If you haven’t already, set up single sign-on for managed Google Accounts using third-party Identity providers.

Step 2:

Set up and test SAML SSO on a test domain you own. If you don’t have a test domain, test SAML SSO with a small number of users by creating a test group and enabling SSO for users only in that group. After testing SAML SSO with a small number of users, roll it out to approximately 5% of your users.

1. Sign in to your Google Admin console.

   Sign in using your administrator account (does not end in @gmail.com).

2. In the Admin console, go to Menu  DevicesChromeSettingsUsers & browsers.
3. To apply the setting to all users and enrolled browsers, leave the top organizational unit selected. Otherwise, select a child organizational unit.
4. Under Single sign-on, select Enable SAML-based single sign-on for Chrome devices from the list.
5. Click Save.

(Optional) Step 3:

To allow single sign-on users to log in to internal websites and cloud services that rely on the same IdP on subsequent sign-ins to their device, you can enable SAML SSO cookies.

1. Sign in to your Google Admin console.

   Sign in using your administrator account (does not end in @gmail.com).

2. In the Admin console, go to Menu  DevicesChromeSettingsDevice.
3. To apply the setting to all devices, leave the top organizational unit selected. Otherwise, select a child organizational unit.
4. Under Single sign-on cookie behavior, select Enable transfer of SAML SSO cookies into user session during sign-in from the list. For more details, see Set ChromeOS device policies.
5. Click Save.

(Optional) Step 4 Keep local ChromeOS and SAML SSO passwords in sync:

You can choose to sync ChromeOS device local passwords with users' SAML SSO passwords.

By default, the local password is updated every time users sign in online. You can configure how often users are required to sign in online using the SAML single sign-on login frequency or SAML single sign-on unlock frequency settings. However, some users might change their SAML SSO password before they’re required to sign in online again. If that happens, users continue to use their old local ChromeOS password until the next time they sign in online.

To keep the local ChromeOS password in sync with their SAML SSO password, you can force them to sign in online as soon as their SAML SSO password changes. That way, they update their ChromeOS password almost immediately.

1. To notify Google of user password changes, you can use any of the following;
   1. IdP integration—For example, if you use Okta, you can use Okta workflows. For details, see GitHub documentation.
   2. AD integration—Change Password Notifier (CPN) notifies Google of Microsoft Active Directory password changes. For details, see Sync ChromeOS passwords using Change Password Notifier.
   3. API integration—Integrate your IdP with the device token API. You can get the Chromedevice token API here. For details, see Enable API suite for cloud project.
2. Configure the relevant settings;
   1. SAML single sign-on password synchronization—Select Trigger authentication flows to synchronize passwords with SSO providers. For details, see Set Chromepolicies for users or browsers.
   2. SAML single sign-on password synchronization flows—Choose whether you want to enforce online sign-ins for the login screen only, or for both the login and lock screen. For details, see Set Chrome policies for users or browsers.

(Optional) Step 5 Notify your users of upcoming password changes:

You can ensure that users are informed of upcoming password changes on their ChromeOS devices.

Note: We recommend that you do either Step 4: Keep local ChromeOS and SAML SSO passwords in sync or Step 5 Notify your users of upcoming password changes, not both.

To inform users about upcoming password changes;

1. Using the Google Admin Console, set up single sign-on for managed Google Accounts using third-party Identity providers.
2. Configure SAML assertion for password expiry for your SAML SSO provider. See the example below.
3. Using the Admin console, configure the settings.
   1. SAML single sign-on login frequency—Enter a value that is smaller than the password expiration time. ChromeOS only updates its assertions during online logins. For details, see Set Chrome policies for users or browsers.
   2. SAML single sign-on password synchronization—Select Trigger authentication flows to synchronize passwords with SSO providers. Specify how many days in advance users should be notified. You can enter a value between 0 and 90 days. Left blank, the default value of 0 is used and users are not notified in advance, only when their password expires. For details, see Set Chrome policies for users or browsers.

Example AttributeStatement

In the example;

• Attribute name contains passwordexpirationtimestamp—The timestamp when the authenticating user's password will expire. Can be empty if the password will not expire, can be in the past if already expired. If you prefer, you can use passwordmodifiedtimestamp instead.
• Attribute value is NTFS filetime—The number of 100ns ticks since 1st of January 1601 UTC. If you prefer, you can set Unix time or ISO 8601 date and time instead. No other formats are accepted.

<AttributeStatement>
<Attribute
     Name="http://schemas.google.com/saml/2019/passwordexpirationtimestamp">
     <AttributeValue>132253026634083525</AttributeValue>
</Attribute>
</AttributeStatement>

(Optional) Step 6:

To allow single sign-on users to navigate directly to your SAML IdP page instead of first having to type in their email address, you can enable SAML SSO IdP Redirection.

1. Sign in to your Google Admin console.

   Sign in using your administrator account (does not end in @gmail.com).

2. In the Admin console, go to Menu  DevicesChromeSettingsDevice.
3. To apply the setting to all devices, leave the top organizational unit selected. Otherwise, select a child organizational unit.
4. Under Single sign-on IdP redirection, select Allow users to go directly to SAML SSO IdP page from the list. For more details, see Set ChromeOS device policies.
5. Click Save.

(Optional) Step 7 Username passthrough:

You can automatically pass usernames from Google Identity to the 3P IdP to avoid users having to type their username twice.

Before you begin

• This feature is only available to IdPs that allow username handover as part of the SAML query. For details, see Autofill username on SAML IdP login page.
• If you always redirect users to the third-party identity provider (3P IdP) by completing step 7, username passthrough is limited to reauthentication flows. For details, see the SAML single sign-on login frequency or SAML single sign-on unlock frequency settings.

1. Sign in to your Google Admin console.

   Sign in using your administrator account (does not end in @gmail.com).

2. In the Admin console, go to Menu  DevicesChromeSettingsDevice.
3. To apply the setting to all devices, leave the top organizational unit selected. Otherwise, select a child organizational unit.
4. Under Autofill username on SAML IdP login page, enter the URL parameter name.
5. Click Save.

Step 8:

After testing SAML SSO for devices on 5% of your organization, you can roll it out to everyone by enabling the same policy for additional groups. If you run into issues, contact Google Cloud support.

Sign in to a ChromeOS device with SAML single sign-on

Once SAML SSO on devices has been configured for your organization, users will see the following steps when they sign in to a device.

Requirements

• You’ve completed all of the steps described above.

Sign-in Sequence:

Instruct your users to do the following when first signing in to their device. Note: You will need to test this before rolling it out to your organization.

1. Enter your username (full email address) on the ChromeOS device sign in page. A password is not needed in this step.
2. You will be taken to your organization’s SAML SSO page. Enter your SAML credentials on the SAML provider login page.
3. If prompted, re-enter your password to complete sign-in. This step is only necessary if your Identity Provider has not yet implemented the Credentials Passing API. This is necessary to allow offline access to your device and also to be able to unlock it.
4. When signed in successfully, your session starts and the browser opens. The next time you sign in, you will only need to enter your password once when you start up your device. If you run into issues, please contact your IT administrator.

FAQs

Can I use Windows Integrated Authentication (WIA) to allow users sign in to browser-based apps and the intranet without having to manually enter their username and password?

No. We no longer support WIA in Active Directory Federation Services (AD FS). For more details, see Migrating to cloud-based Chrome management.

After signing in with my SAML provider, I am prompted to re-enter my password. Is that normal?

Yes. This is necessary to allow offline access to your ChromeOS device and to be able to unlock it. We have an API that SAML vendors can implement to remove the need for this confirmation step.

If a user changes their password on another device, how do you make sure the device gets updated to unlock with the new password?

We recommend you use the simple update method on our Directory API which will notify our authentication server when a password is changed. Enter the password value in the Request body. If the API is not used, the password change will be detected at the next online login flow. By default, the device will force an online sign in every 14 days even if the password didn't change. You can change this period in the Admin console by going to DevicesChromeSettingsUsers & browsersSAML single sign-on online login frequency.

My password has special characters, will it work?

We support ASCII printable characters only.

I see the screen “Oops, couldn't sign you in. Sign-in failed because it was configured to use a non-secure URL. Please contact your administrator or try again”. What should I do?

If your employees are reporting this error message, it means that the SAML IdP is trying to use an HTTP URL and only HTTPS is supported. It is important that the entire sign-in flow uses HTTPS only. So even if the initial sign-in form is served over HTTPS, you can get this error if your IdP redirects to an HTTP URL somewhere later in the process. If you fix this and users are still getting the error message, please contact Google Cloud support.

I am an IT administrator. Why am I am not being redirected to my SAML Identity Provider?

This is by design. In the event of something going wrong during setup, we still want the administrator to be able to login and troubleshoot the problem.

Does SSO work with TLS and SSL content filters?

Yes. Please follow Set up TLS (or SSL) inspection on ChromeOS devices for setup. In addition to allowed domains documented in Set up a host name allowlist, you also need to allow your SSO Identity Provider domain and www.google.com.

How does SSO work with camera permissions?

To give third party software direct access to the device camera on behalf of your SSO users, you can enable single sign-on camera permissions.

Go to DevicesChromeSettingsDeviceSingle sign-on camera permissionsAllowlist of single sign-on camera permissions.

For more details, see Set ChromeOS device policies.

By enabling this policy, the administrator grants third parties access to their users' cameras on their users' behalf. The administrator should ensure that they have proper consent forms in place for users as the system does not show end users any consent forms once camera permission is granted via this policy.

Google and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.