Use the Certificate Enrollment for ChromeOS extension

As an administrator you can use the Certificate Enrollment for ChromeOS extension to enable a user to get a user or device certificate either manually or automatically. You can also set up the automatic renewal of existing certificates that are expiring.

Before using the extension, ensure that users have access, and that the extension and associated managed policy are properly configured. For more help with setting up the extension, see the Extension deployment guide section.

Certificate request types

There are two types of certificate requests; user certificate requests and device certificate requests.

  • User certificate requests result in a certificate being issued for the specific user sending the request, not the overall device. User certificates are only valid for the user logged into that machine, not any other users who may also use the machine.
  • Device certificate requests result in a certificate being issued for the overall device sending the request, not just the user sending the request. Device certificates are valid for all users belonging to the same organization on the machine, which is typically necessary for devices being used in managed guest session or kiosk mode.

Certificate provisioning without user-entered credentials

You can configure the certificate enrollment extension to automatically provision or renew a certificate without requiring a user to manually enter credentials

When you configure one of the new provisioning or renewal options, the extension automatically detects if a certificate is not already provisioned on a device or if it is expiring soon, triggering a notification asking the user to get or renew a certificate. The user must click on the notification, and the extension starts the process of getting or renewing the certificate. For details, see the Extension deployment guide section.

Enroll a certificate

To automatically enroll a pre-configured certificate, the user must:

  1. Click the Enroll Certificate notification.
  2. (Optional) Select the Enroll Device-Wide Certificate box to request a device certificate. If the box is left unchecked, a user certificate is requested.
  3. Click Enroll.
Renew a certificate

To renew a certificate, the user must only click on the Certificate Renewal Reminder notification.

Certificate provisioning with user-entered credentials

You can configure the certificate enrollment extension to let users manually provision a certificate

Primary user flows

User flows in the extension are broken down into primary and secondary categories. A primary user flow, described in this section, is something a user should typically expect to encounter.

Create a user certificate request

User certificate requests are requests that should result in a certificate being issued for the specific user sending the request, not the overall device. User certificates are only valid for the user logged into that machine, not any other users who may also use the machine.

  1. Click or tab navigate to the Username field.
  2. Enter your username.
  3. Click or tab navigate to the Password field.
  4. Enter your password.
  5. Leave the Device-Wide box unchecked.
Create a device certificate request

Device certificate requests are requests that should result in a certificate being issued for the overall device sending the request, not just the user sending the request. Device certificates are valid for all users belonging to the same organization on the machine, which is typically necessary for devices being used in Public Session or kiosk mode.

  1. Click or tab navigate to the Username field.
  2. Enter your username.
  3. Click or tab navigate to the Password field.
  4. Enter your password.
  5. Check the Device-Wide box.
Send a certificate request

Regardless of the type of request being sent (user or device), the process to send one is the same.

  1. Create either a user or device certificate request, as specified in the steps above.
  2. Navigate to the Enroll button.
  3. Click Enroll.
Successfully receive and import a certificate

Once a request is sent, the ideal outcome is a success response from the server which will include the certificate requested.

  1. Send a Certificate Request, as specified above.
  2. Wait for the response to be received.
  3. When a response is received, a dialog will display with a success message to signify that the certificate was received and imported.
  4. Select Okay in the dialog, hit the escape key, or click outside of the dialog to close it when done.
Receive an error response

Once a request is sent, sometimes the request can fail for a variety of reasons. An error response encapsulates these failures and will inform the user of what the problem is.

  1. Send a Certificate Request, as specified above.
  2. Wait for the response to be received.
  3. When a response is received, a dialog will display with a failure message to signify that something went wrong.
  4. Select Okay in the dialog, hit the escape key, or click outside of the dialog to close it when done.
  5. If the error is correctable (such as invalid username), then performing the correction and resending the request should result in success. If not (such as when the request is denied access by the server), then the user should seek help.

Secondary user flows

Secondary user flows, described below, should occur only rarely.

Receive a Pending Certificate Response

Once a request is sent, sometimes the server can set that request to pending in order for someone to manually review and approve/reject the request later. A pending response encapsulates this flow and will inform the user of the relevant information to check on the status of the request later.

  1. Send a Certificate Request, as specified above.
  2. Wait for the response to be received.
  3. When a response is received, a dialog will display with a pending message to signify that the request was set to pending. It will also display the enrollment URI and request ID of the request, which are necessary to check on it later.
  4. Copy the enrollment URI and request ID somewhere to refer to later.
  5. Select Okay in the dialog, hit the escape key, or click outside of the dialog to close it when done.
Navigate to Pending Request UI

If a user has a pending certificate, then the user may want to check on the certificate’s status at some point. In order to create and send pending certificate requests, the user must navigate to the pending request UI.

  1. Click or tab navigate and select the More Options button.
  2. From the list of options generated, click or tab navigate to the ‘Show extra fields for checking on pending requests?’ option.
  3. Select ‘Show extra fields for checking on pending requests?’ to enable the pending request fields to display.
Navigate Back to Regular Request UI

If a user has previously navigated to the pending request UI, then the user may want to navigate back to the regular at some point.

  1. Click or tab navigate and select the More Options button.
  2. From the list of options generated, click or tab navigate to the Hide extra fields for checking on pending requests?’ option.
  3. Select Hide extra fields for checking on pending requests?’ to disable the pending request fields from displaying.
Create a Pending Certificate Checkup Request

If a user has a pending certificate, then the user may want to check on the certificate’s status at some point. The extension allows this flow very similarly to creating a brand new request.

  1. Navigate to Pending Request UI, as specified above.
  2. Click or tab navigate to the Username field.
  3. Enter your username.
  4. Click or tab navigate to the Password field.
  5. Enter your password.
  6. Click or tab navigate to the Enrollment URI field.
  7. Enter the enrollment URI displayed in a previous pending certificate response.
  8. Click or tab navigate to the Request ID field.
  9. Enter the request ID displayed in a previous pending certificate response.
  10. If the original certificate request was for a device-wide certificate, then check the Device-Wide checkbox. Otherwise, leave the Device-Wide checkbox unchecked.
Send a Pending Certificate Checkup Request

Once a pending certificate checkup request has been created, the user needs to send that request in order to get a response. A pending certificate checkup request can result in a success, failure, or still pending response, which matches the flows already defined above.

  1. Create a Pending Certificate Checkup Request, as specified above.
  2. Navigate to the Check Status button.
  3. Select the Check Status button.
Copy Logs to the Clipboard

Sometimes in cases of errors, it may be helpful for an assistant or administrator to see the full logs of what happened in the extension. In order for a user to obtain these logs, we provide a simple method to copy them to the user’s clipboard.

  1. Click or tab navigate and select the More Options button.
  2. From the list of options generated, click or tab navigate to the ‘Copy Logs to Clipboard’ option.
  3. Select ‘Copy Logs to Clipboard’ to have the logs copied to the user’s clipboard.
  4. From here, the user can paste these logs anywhere the user chooses through the normal process for the user’s device.

Extension deployment guide

Applies to managed Chromebooks only.

As an administrator, you can let Chromebook users access your organization’s protected networks and internal resources that require a certificate for authentication. Remotely install and configure the Certificate Enrollment for ChromeOS extension so that your users can request user or system certificates on Chromebooks.

Alternatively, you can set up automated certificate provisioning using Kerberos authentication for user or device certificates or hosted service account authentication for device certificates. You can also set the extension to renew existing certificates without additional authentication using key-based renewal.

The extension also lets you scale your rollout of ChromeOS devices by automating the Microsoft Active Directory certificate enrollment process through the Google Admin console.

Before you begin

To let users request digital certificates, you need:

  • Microsoft Windows Server 2008 R2 or later
  • Microsoft Internet Information Services (IIS) 7.0 or later
  • Active Directory Certificate Services (ADCS) including:
    • Certificate enrollment service (CES)
    • Certificate enrollment policy (CEP)
    • A valid certificate associated to the ADCS website in IIS
    • A visible endpoint for CEP and CES

Disclaimer

This guide describes how Google products work with third-party products and the configurations that Google recommends. Google does not provide technical support for configuring third-party products. Google accepts no responsibility for third-party products. Go to the product's website for the latest configuration and support information.

Deploy the extension

Open all   |   Close all

Step 1: Force-install the extension for 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 and then Devicesand thenChromeand thenApps & extensionsand thenUsers & browsers.

    If you signed up for Chrome Browser Cloud Management, go to Menu and then Chrome browserand thenApps & extensionsand thenUsers & browsers.

  3. (Optional) To apply the setting to a department or team, at the side, select an organizational unit. Show me how
  4. Point to Add Add question and then Add from Chrome Web Store.
  5. Search for and select Certificate Enrollment for ChromeOS. The extension ID is fhndealchbngfhdoncgcokameljahhog.
  6. On the Users & Browsers page, select the Certificate Enrollment for ChromeOS extension.
  7. In the panel on the right, under Certificate management, turn on Allow access to keys.
  8. Under Installation policy, choose Force install or Force install + pin to ChromeOS taskbar.
  9. Click Save.
Step 2: Set the extension's configuration

Create a file that contains the settings that you want to apply to the Certificate Enrollment for ChromeOS extension for users. Start with this sample file and change the policies to suit your organization’s or users’ needs. You can edit the JavaScript Object Notation (JSON) file using a text editor.

Note: Policies that contain default values in user-facing strings are translated and appear on devices according to the user’s locale. You can change strings to suit your organization’s needs, but they won’t be translated.

You can set the following policies:

Policy name What it does

allow_machine_cert_enrollment

Allows users to install a system certificate.

If set to true, users can choose to request a system or user certificate. Otherwise, they can only request a user certificate.

The default is false.

cep_proxy_url

Specifies the https endpoint for the CEP.

To get the endpoint:

  1. In IIS Manager, go to the CEP website.
    The name usually contains CEP.
  2. Open Application Settings.
    The https endpoint for the CEP is listed there under URI.

Only values that start with https are valid. If you enter a value that starts with https but does not match the Uniform Resource Identifier (URI) in IIS Manager, it will still be considered to be valid and will be used, but will most likely fail.

This policy is mandatory.

company_info

Specifies your organization’s branding information, such as name and logo.

  • Set help_url to direct users to a webpage where they can get information or support.
  • If the webpage that you specify is blocked for users without a certificate, such as on first request, use help_text to provide some helpful text to them.
  • If you set help_url and help_text, the webpage you specified appears below the help text on users’ devices.

device_cert_request_values

Specifies the values to be used in the certificate signing request (CSR) for a device certificate.

Instead of using the requester’s properties, you can define subject values based on user and device attributes. To use custom CSR, you should also configure the certificate template on the certificate authority (CA) to expect and generate a certificate with the subject values defined in the request itself. At minimum, you need to provide a value for the subject's CommonName.

You can use the following placeholders. All values are optional.

For ChromeOS devices running version 66 and later, you can use:

  • ${DEVICE_DIRECTORY_ID}—Device’s directory ID
  • ${USER_EMAIL}—Signed-in user’s email address
  • ${USER_DOMAIN}—Signed-in user’s domain name
  • ${DEVICE_SERIAL_NUMBER}—Device's serial number
  • ${DEVICE_ASSET_ID}—Asset ID assigned to device by administrator
  • ${DEVICE_ANNOTATED_LOCATION}—Location assigned to device by administrator

If a placeholder value isn’t available, it’s replaced with an empty string.

You can chain placeholders. For example, ${DEVICE_ASSET_ID:DEVICE_SERIAL_NUMBER} is replaced by the device’s serial number if the asset ID isn’t available.

device_enrollment_templates

List of matching certificate template names in order of priority for user-enrollment flows. The extension searches the list to find a matching certificate template. The first matching certificate template is used. If there’s an error, the extension doesn’t retry with other certificate templates.

This policy is mandatory. It must have at least one value in the list.

From the CA Microsoft Management Console (MMC), use the Template name and not the Template display name.

The default is ChromeOSWirelessUser.

enable_auto_enrollment

Controls whether the extension automatically initiates enrollment. If set to false, the extension waits for the user to attempt to connect to the EAP-TLS network.

The default is false.
log_level

Specifies the level of detail in the extension’s logs that are sent to the JavaScript console in Chrome.

NONE (default)—Nothing is logged to the console.

ERROR—Only distinct errors are logged to the console.

WARNING—Distinct errors and warnings are logged to the console.

INFO—Distinct errors and warnings along with relevant action information are logged to the console.

DEBUG—Everything is logged to the console. For the initial version, this setting is recommended to troubleshoot potential issues. In More Options, you can automatically copy all logs to the clipboard.

There are 2 ways that users can open the web developer console in Chrome to access the Chrome logs on their device:

  • Press Ctrl+Shift+i.
  • Click More toolsand thenDeveloper tools.

This policy is mandatory.
placeholder_values

Specifies the username, password, URI, request ID, and header placeholders. This information helps guide users when they’re signing in.

  • The Username, Password, URI, and RequestID fields are displayed over the input fields to show what each input field does.
  • The Header field is used for the page’s title.
  • There are special values for the Username, Password, and Header fields that allow customers to use internationalized default names.
    • managed_username_placeholder—Username
    • managed_password_placeholder—Password
    • managed_login_header—Certificate enrollment
  • If your organization uses other terminology, such as passphrase instead of password, you can change the values. However, the new value isn’t translated.
renew_hours_before_expiry

Specifies the length of time, in hours, prior to certificate expiration to notify users of an expiration.

 

The default is 120.
renew_reminder_interval

Controls how often, in hours, prior to certificate expiration that users are notified.

After the initial notification, if the user does not renew the certificate and does not choose to ignore reminders, they’ll see further notifications after the amount of hours set.

For example, if you set renew_hours_before_expiry to 120 and renew_reminder_interval to 24 and a user always chooses to receive further reminders, then the user receives 5 renewal notifications, one each day, until the certificate expires.

The default is 24.

request_timeout_seconds

The length of time, in seconds, before a call to CEP or CES times out.

The default is 20.

signature_algo

Controls what signature algorithm the extension uses to sign certificate requests. Options are:

  • SHA1 (not recommended)—Weak algorithm that can compromise the security of your users
  • SHA256
  • SHA512 (default)

user_cert_request_values

Specifies the values used in the certificate signing request (CSR) for a user certificate.

Instead of using the requester’s properties, you can define subject values based on user and device attributes. To use custom CSR, you should also configure the certificate template on the CA to expect and generate a certificate with the subject values defined in the request itself. At minimum, you need to provide a value for the subject's CommonName.

You can use the following placeholders. All values are optional.

  • ${DEVICE_DIRECTORY_ID}—Device’s directory ID

  • ${USER_EMAIL}—Signed-in user’s email address

  • ${USER_DOMAIN}—Signed-in user’s domain name

  • ${DEVICE_SERIAL_NUMBER}—Device's serial number

  • ${DEVICE_ASSET_ID}—Asset ID assigned to device by administrator

  • ${DEVICE_ANNOTATED_LOCATION}—Location assigned to device by administrator

  • ${USER_ID}—First part (part before @) of signed-in user’s email address

If a placeholder value isn’t available, it’s replaced with an empty string.

You can chain placeholders. For example, ${DEVICE_ASSET_ID:DEVICE_SERIAL_NUMBER} is replaced by the device’s serial number if the asset ID isn’t available.

user_enrollment_templates

List of matching certificate template names in order of priority for user-enrollment flows. The extension searches the list to find a matching certificate template. The first matching certificate template is used. If there’s an error, the extension doesn’t retry with other certificate templates.

This policy is mandatory. It must have at least one value in the list.

From the CA MMC, use the Template name and not the Template display name.

The default is ChromeOSWirelessUser.

Configure certificate provisioning with or without user-entered credentials

By default, the certificate enrollment extension is set up to let users manually provision a certificate by providing their credentials when trying to get a certificate.

You can ensure users can automatically provision or renew a certificate without having to manually enter their credentials by using the ChromeOS extension. The extension can request both user and device certificates using Kerberos authentication if a user Kerberos ticket is available on the device. It can also request device certificates only using a service account.

Kerberos authentication

Before you begin

  • The ChromeOS user must have a Kerberos ticket on the device.
  • The Active Directory user account associated with the Kerberos ticket must have permission to request certificates using the configured Certificate Template.
  • The enrollment endpoint must be listed in the Integrated authentication servers ChromeOS policy. For details see the policy in the Chrome Policy list.

Configure the extension

Set the extension policy value `client_authentication` to `kerberos`.

Hosted service account authentication

You can set the extension to request a device certificate using a service account. The credentials for the service account are hosted on a web server on your local network.

Warning: If an attacker gains access to the web server hosting the credentials and the extension policy on the device, there is the possibility that they can extract the service account credentials.

We recommend restricting access to the web server that hosts the service account credentials to a provisioning network that is only used for initial ChromeOS device provisioning.

Before you begin

  • You must have a web server on the local network that can handle HTTPS requests.
  • ChromeOS must trust the certificate of that web server. If the web server uses a certificate issued by a self-signed CA, you can configure the CA’s certificate to be trusted in the Admin console.

Step1: Generate the masked password

  1. Open the extension.
  2. Select Moreand thenPassword Mask Tool.
  3. Enter the service account password.
  4. Select Mask.
  5. Copy the mask and the masked password into a text file.

Step 2: Store credentials on the internal web server

  1. Configure the web server to serve a JSON file that contains the following:

{

  ‘username’: ‘<service account username>’,

  ‘maskedPassword’: ‘<copy and pasted masked password>’

}

  1. Copy the URL that the web server is using to host the credentials into a text file.

Step 3: Configure the extension policy

  1. Set the extension policy variable ‘service_account_host’ to the URL you copied above.
  2. Set the extension policy variable ‘service_account_host_password_mask’ to the mask you copied above.

Automated certificate renewal

You can set the extension to renew existing certificates without additional authentication using key-based renewal.

Before you begin

An ADCS Certificate Enrollment Service (CES) endpoint that supports key-based renewal for the configured Certificate Template must be available. For details, see Configuring Certificate Enrollment Web Service for certificate key-based renewal on a custom port.

Configure the extension

  • Set the extension policy value `use_key_based_renewal` to true.
  • Set the extension policy value ‘ces_renewal_url’ to the URL of the Certificate Enrollment Service (CES) endpoint that supports key-based renewal.
Step 3: Validate the JSON file
Use your preferred tool to validate your configuration file to make sure that there are no errors in the JSON code. If you find errors, check the syntax and structure of your configuration file, make corrections, and validate it again.
Step 4: Apply the extension policy
To make settings for a specific group of users or enrolled Chrome browsers, put the user accounts or browsers in a group or organizational unit. Only user accounts can be added to groups. For details, see Groups and Add an organizational unit.
  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 and then Devicesand thenChromeand thenApps & extensionsand thenUsers & browsers.

    If you signed up for Chrome Browser Cloud Management, go to Menu and then Chrome browserand thenApps & extensionsand thenUsers & browsers.

  3. (Users only) To apply the setting to a group, do the following:
    1. Select Groups.
    2. Select the group to which you want to apply the setting.
  4. (Optional) To apply the setting to a department or team, at the side, select an organizational unit. Show me how
  5. Find and select the Certificate Enrollment for ChromeOS extension.
  6. In the panel on the right, under Policy for extensions in the text field, enter the JSON data that you created in Step 2.
  7. Under Installation policy, choose Force install or Force install + pin to ChromeOS taskbar.
  8. Click Save.
Step 5: (Optional) Configure the Wi-Fi network to enroll with the extension
  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 and then Devicesand thenNetworks.
  3. Click Wi-Fi.
  4. Add a new EAP-TLS network.
    For details about how to add a Wi-Fi network configuration, see Manage networks.
  5. Point the network to the enrollment extension. In the Client enrollment URL field, enter chrome-extension://fhndealchbngfhdoncgcokameljahhog/html/request_certificate.html.

Note: The enrollment extension URL is accessible in Chrome browser even if no networks are configured to enroll at this URL. This setup lets you test the URL manually before you configure any networks or enroll certificates for uses other than EAP-TLS networks, such as certificate-based VPN. Tell users to go to the URL in their browser and skip the network configuration step.

Step 6: Verify policies are applied
After you deploy the Certificate Enrollment for ChromeOS extension, users need to restart their devices for the settings to take effect. You can check users’ devices to make sure the policy was applied correctly.
  1. On a managed ChromeOS device, go to chrome://policy.
  2. Click Reload policies.
  3. Scroll to Certificate Enrollment for ChromeOS.
  4. For each policy, make sure that the value fields are the same as what you set in the JSON file.

Troubleshoot digital certificate requests

Applies to managed Chromebooks only.

Here's how to fix problems you might have when users request digital certificates.

Error messages in extension’s UI

Could not find a valid system token. Your device may not be enrolled in the domain, or you may not have rights to request a system certificate.

Make sure that the Certificate Enrollment for ChromeOS extension is force-installed for your users.

Error messages in Chrome console logs

Could not enroll to the specified uri.

Check the permissions for authenticated users set in the CA template. Then, make sure that relevant users have the appropriate privileges.

Extension requests incorrect enrollment endpoints.

Check the Certificate Enrollment for ChromeOS extension’s console logs to make sure the URL request is correct.
  • Correct URL request—https://userNameGoesHere:passWordGoesHere@yourCEPServiceUriGoesHere
  • Incorrect URL request—chrome-extension://userNameGoesHere:passWordGoesHere@fhndealchbngfhdoncgcokameljahhog/html/request_certificate.html

Users might have URL request issues when the Certificate Enrollment for ChromeOS extension is first installed and has no existing state information. Or, issues might arise when the extension is updated and loses its previous state information.

When you want to push a new or updated policy to the extension, first push an empty policy so that all current policy values are flushed and reset. Then, push the policy you want.

  1. Push an empty policy.
  2. Verify policies are applied on users’ devices.
  3. Push the policy you want.
  4. Verify policies are applied on users’ devices.
  5. Refresh the Certificate Enrollment for ChromeOS extension.

No enrollment uris available to enroll to.

In most cases, the Certificate Enrollment Policy (CEP) can’t find your configured template. Check the CA for the more typical causes:
  • Make sure that you configured the role services for Certificate Enrollment to accept username and password authentication (not Kerberos, for example).
  • Make sure that your extension configuration is defined to use the correct CA template.
  • Ensure that the value entered in the user_enrollment_templates policy in the JSON file is the same as the CA’s Template name, not the Template display name.
  • Check the permissions for authenticated users set in the CA template. Then, make sure that relevant users have the appropriate privileges.

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.

Was this helpful?

How can we improve it?

Need more help?

Try these next steps:

Post to the help community Get answers from community members
true
Search
Clear search
Close search
Main menu
10241342333087696506
true
Search Help Center
true
true
true
true
true
410864
false
false