Configure Kerberos single sign-on for ChromeOS devices

For administrators who manage ChromeOS devices for a business or school.

As an admin, you can use Kerberos tickets on ChromeOS devices to enable single sign-on (SSO) for internal resources that support Kerberos authentication. Internal resources might include websites, file shares, certificates, and so on.

Requirements

• Devices with ChromeOS version 91 or later.
• Kiosks are not currently supported.
• Active Directory environment.

Set up Kerberos

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  DevicesChromeSettings. The User & browser settings page opens by default.

   If you signed up for Chrome Browser Cloud Management, go to Menu  Chrome browserSettings.

3. (Optional) At the top, click Managed guest session settings.
4. To apply the setting to everyone, leave the top organizational unit selected. Otherwise, select a child organizational unit.

5. Go to Kerberos.

6. Click Kerberos tickets.

7. Select Enable Kerberos.

8. (Optional) (Users & browsers only) Automatically request Kerberos tickets for users when they sign in.

   1. Select Automatically add a Kerberos account.

   2. Enter the Principal name. ${LOGIN_ID} and ${LOGIN_EMAIL} placeholders are supported.

   3. Select Use default Kerberos configuration. Or, select Customize Kerberos configuration and specify the Kerberos configuration that you need to support your environment. For details, see Configure how to get tickets.
      Note: You should review your Kerberos configuration, krb5.conf. The default configuration enforces strong AES encryption which might not be supported by every part of your environment.

9. Click Save.

Configure how Kerberos can be used on devices

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  DevicesChromeSettings. The User & browser settings page opens by default.

   If you signed up for Chrome Browser Cloud Management, go to Menu  Chrome browserSettings.

3. (Optional) At the top, click Managed guest session settings.
4. To apply the setting to everyone, leave the top organizational unit selected. Otherwise, select a child organizational unit.
5. Go to Network.
6. Configure allowed authentication servers:
   1. Click Integrated authentication servers.
   2. Enter URLs of websites that are protected by Kerberos. Users can use their active ticket to access the servers that you list, without having to sign in.
      Note: You can add multiple server names, separated with commas. Wildcards, *, are allowed. Don’t include wildcards in the domain name. For example, avoid adding *example.com to the list. Here is a sample list *.example.com, example.com.
   3. Click Save.
7. (Users & browsers only) Configure allowed servers for delegation:
   1. Click Kerberos delegation servers.
   2. Enter URLs of the servers that Chrome can delegate to.
      Note: You can add multiple server names, separated with commas. Wildcards, *, are allowed.
   3. Click Save.
8. (Users & browsers only) Specify whether to respect Key Distribution Center (KDC) policy to delegate Kerberos tickets:
   1.  Click Kerberos ticket delegation.
   2. Choose an option:
      • Respect KDC policy
      • Ignore KDC policy
   3. Click Save.
9. (Users & browsers only) Specify the source of the name used to generate the Kerberos service principal name (SPN).
   1. Click Kerberos service principal name.
   2. Choose an option:
      • Use canonical DNS name
      • Use original name entered
   3. Click Save.
10. (Users & browsers only) Specify whether the generated Kerberos SPN should include a non-standard port.
    1. Click Kerberos SPN port.
    2. Choose an option:
       • Include non-standard port
       • Do not include non-standard port
    3. Click Save.
11. (Users & browsers only) Specify whether third-party sub-content on a page is allowed to pop-up an HTTP basic authentication dialog box.
    1. Click Cross-origin authentication
    2. Choose an option:
       • Allow cross-origin authentication
       • Block cross-origin authentication
    3. Click Save.

What users can do

Add a ticket

When users try to access a Kerberos-protected resource, they are given the option to add a ticket or continue without one.

To add a ticket, do the following;

1. In the box, click Manage tickets.
2. In the Kerberos tickets page, click Add a ticket.
3. Enter your Active Directory username and password.
   Note: ChromeOS only supports the user@domain notation, not the domain/user notation.
4. (Optional) To automatically refresh the ticket, keep the Remember password box checked.
5. (Optional) Edit the configuration file:
   • Click Advanced.
   • Change Kerberos configuration information, such as ticket lifetime, encryption types, and domain-realm mappings. For details, see Configure how to get tickets.
   • Click Save.
6. Click Add.
7. Reload the page you are trying to view.

Note: Kerberos requires a certain DNS setup, in particular SRV records for the _kerberos and _kerberos-master services. For details, see Troubleshoot below.

Set active ticket

Users can add multiple Kerberos tickets on their ChromeOS devices. But only one ticket can be active and used for authentication at any given time. Users can access resources that require different authorization levels by switching tickets. For example, if certain internal webpages require a Kerberos ticket with a higher privilege level.

1. If you haven't yet, sign in to a managed ChromeOS device.
2. At the bottom right, select the time.
3. Click Settings .
4. In the People section, click Kerberos tickets.
5. Find the ticket that you want to set active.
6. On the right, click More Set as active ticket.

Refresh a ticket and modify configuration

By default, tickets are valid for 10 hours and can be renewed for a week without users having to re-entering their username and password. When a ticket expires and can’t automatically refresh, users see a message telling them that they need to refresh the ticket manually. If users let the active ticket expire, Kerberos authentication no longer works until they refresh the ticket.

1. If you haven't yet, sign in to a managed ChromeOS device.
2. At the bottom right, select the time.
3. Click Settings .
4. In the People section, click Kerberos tickets.
5. Find the ticket that you want to refresh.
6. Click Refresh.
   If the ticket is not near its expiration, on the right, click More Refresh now.
7. Enter your Active Directory username and password.
   Note: ChromeOS only supports the user@domain notation, not the domain/user notation.
8. (Optional) To automatically refresh the ticket, check the Remember password checkbox.
9. (Optional) Edit the configuration file.:
   1. Click Advanced.
   2. Change Kerberos configuration information, such as ticket lifetime, encryption types, and domain-realm mappings. For details, see Configure how to get tickets.
   3. Click Save.
10. Click Refresh.

Remove a ticket

1. If you haven't yet, sign in to a managed ChromeOS device.
2. At the bottom right, select the time.
3. Click Settings .
4. In the People section, click Kerberos tickets.
5. Find the ticket that you want to remove.
6. On the right, click More Remove from this device.

Configure how to get tickets

Users can modify the Kerberos configuration, krb5.conf, when they add a new ticket or refresh an existing ticket. The ChromeOS code that interacts with the Kerberos key distribution center (KDC) is based on the MIT Kerberos library. For configuration details, go to MIT Kerberos documentation. However, we do not support all options.

Here is a list of the options that ChromeOS supports:

Section	Relation
[libdefaults]	canonicalize clockskew default_tgs_enctypes default_tkt_enctypes dns_canonicalize_hostname dns_lookup_kdc extra_addresses forwardable ignore_acceptor_hostname kdc_default_options kdc_timesync noaddresses permitted_enctypes preferred_preauth_types proxiable rdns renew_lifetime ticket_lifetime Udp_preference_limit
[realms]	admin_server auth_to_local kdc kpasswd_server master_kdc
[domain_realm]	Any value
[capaths]	Any value

Example: Request a different ticket lifetime

[libdefaults]

        ticket_lifetime = 16h

The example requests a ticket valid for 16 hours. The lifetime might be limited server-side, where the default is 10 hours.

To change the server-side limit:

1. Open your Group Policy Management Console.
2. Go to SettingsSecurity settingsAccount policiesKerberos policy.
3. Modify the Maximum lifetime for user ticket policy.

Example: Request a different ticket renewal lifetime

[libdefaults]

        renew_lifetime = 14d

The example requests a ticket that can be renewed for 14 days. The renewal lifetime might be limited server-side, where the default is 7 days.

To change the server-side limit:

1. Open your Group Policy Management Console.
2. Go to SettingsSecurity settingsAccount policiesKerberos policy.
3. Modify the Maximum lifetime for user ticket renewal policy.

Troubleshoot

In general, you can troubleshoot problems using the kinit command line tool on Linux. ChromeOS is Linux-based and the Kerberos tickets implementation uses kinit. So, if you can get a Kerberos ticket using kinit on Linux, you should also be able to get a ticket on ChromeOS with the same configuration.

Error message: KDC does not support encryption type

Google enforces strong AES encryption by default. If you see an error about encryption types, it’s possible that parts of your server environment cannot handle AES encryption. We recommend that you fix this.

Otherwise, consider removing the 3 lines for default_tgs_enctypes, default_tkt_enctypes, and permitted_enctypes from the configuration for development. This will enable all encryption types in MIT Kerberos documentation except the ones marked as weak. Check to make sure that the security implications are acceptable for your needs. Some encryption types are no longer considered strong.

After you confirm that the set of all encryption types works, we recommend that you limit encryption types for default_tgs_enctypes, default_tkt_enctypes, and permitted_enctypes to an appropriate subset of types to minimize security risk.

Error message: Contacting server for realm failed

1. Verify that you entered the correct Kerberos username.
   The Kerberos username, [e-mail], consists of:
   • User sign-in name, also known as sAMAccountName
   • Kerberos realm, that usually matches the Windows domain name
2. Make sure that the network connection is set up correctly.
   Ensure that the server can be reached from the ChromeOS device at the standard Kerberos port 88.
3. Verify that DNS is set up correctly.
   Kerberos requests certain DNS SRV records to find the DNS domain name of the Kerberos service. For instance, if the login domain, or realm, is example.com and the DNS domain name of the only Kerberos service is dc.example.com, the following DNS SRV records should be added:

Service	Protocol	Priority	Weight	Port	Target (Hostname)
_kerberos	_udp.dc._msdcs	0	100	88	dc.example.com
_kerberos	_tcp.dc._msdcs	0	100	88	dc.example.com
_kerberos	_udp	0	100	88	dc.example.com
_kerberos	_tcp	0	100	88	dc.example.com
_kerberos-master	_udp.dc._msdcs	0	100	88	dc.example.com
_kerberos-master	_tcp.dc._msdcs	0	100	88	dc.example.com
_kerberos-master	_udp	0	100	88	dc.example.com
_kerberos-master	_tcp	0	100	88	dc.example.com

If you cannot modify DNS settings, you can add these mappings in the Kerberos configuration.

For example:

[realms]

        EXAMPLE.COM = {

            kdc = dc.example.com

        master_kdc = dc.example.com

}

If you still have problems getting Kerberos tickets, gather system logs. Also collect tcpdump or wireshark logs, if possible. Then, contact support.

Error message: Username not known to server

Verify that the user with the given sign-in name exists in the Active Directory database of the server.

Error message: Couldn’t get Kerberos ticket. Try again, or contact your organization’s device admin. (Error code X).

Gather system logs and contact support.

Related topics

• How to collect ChromeOS device logs