the Chromium logo

The Chromium Projects

Running the cloud policy test server

Chromium can pull down enterprise policy configuration from a cloud service. We have a simplistic python implementation of the management service, so we are able to test features without relying on a full cloud policy server implementation. This page explains how to run it:

Running the test server

  1. You need a Linux Chromium checkout that's in good shape for building the browser. See Get the Code

  2. Make sure you have the protocol buffer source compiled (add the device_policy_proto to the line below if you're building for Chrome OS):

    ninja -C out/Debug py_proto components/policy/core/common full_runtime_code_generate
    
  3. Start the test server. You can start testserver.py directly from the src/ directory of your Chrome source tree:

    OUT_DIR=out/Debug \
    PYTHONPATH=third_party/tlslite:third_party/pywebsocket3/src:$OUT_DIR/pyproto:net/tools/testserver:third_party/protobuf/python:$OUT_DIR/pyproto/components/policy/proto:$OUT_DIR/pyproto/third_party/shell-encryption/src:$OUT_DIR/pyproto/third_party/private_membership/src \
    python components/policy/test_support/policy_testserver.py --data-dir ~/tmp/ --host 127.0.0.1 --port 8889
    

    Note: replace out/Debug with out/Release if appropriate, depending on your build configuration. If this fails with a Python error, try running inside an isolated Python environment via virtualenv. If you want logging, add these flags:

    --log-level DEBUG --log-to-console
    

    Notes on parameters:

    • --data-dir specifies the directory from which the server will read the policy file (see below). Up to you where to place it.
    • --port specifies the port the server should listen on, you can pick a port of your liking.
    • --host The IP address the server should bind to. Note that if you want to test a Chromium OS image running on a Chromebook or in a Virtual Machine against the server, you need to specify the host name or IP address of the public interface in your machine. Note that the server only accepts connections from that IP. To work around these restrictions you can use a port forwarding (ssh is your friend) or local proxy server.
    • --client-state specifies a file in which to persist current server state. This is useful if you want the server to remember registered clients and such across server restarts, for example when your tinkering with the python code in policy_testserver.py to create specific error conditions etc.
    • --config-file specifies a file that contains server configuration. If not specified, the server will default to the device_management file in the data directory.
    • --policy-key a PEM-encoded file containing a private RSA key used to sign policy blobs. More information on the policy blob format and signatures is here. Note that for signing keys to be accepted by Chrome, a verification signature is required that certifies the signing key. These signatures are checked against a Google-owned key pair, the public half of which is baked into the chrome binary. The policy test server contains hardcoded verification signatures for a couple test domains. If you specify a policy key on the command line, the server will try to load a verification signature from the file that's named like the policy key file, but with ".sig" appended. Multiple policy keys may be specified in the command line in order to test key rotation.
  4. Check whether the server answers requests. Point your browser to http://localhost:8889/test/ping (or the public IP you've passed to the --host switch). The server should respond with a page saying "Policy server is up."

  5. Ready to roll!

Setting up a configuration file

The configuration file is a JSON file containing server-global parameters. Here's an example:

{
  "managed_users": [ "*" ],
  "policy_user": "madmax@managedchrome.com",
  "current_key_index": 0,
  "service_account_identity": "",
  "robot_api_auth_code": "",
  "invalidation_source": 0,
  "invalidation_name": "",
  "device_state": {
    "management_domain": "managedchrome.com",
    "restore_mode": 2
  }
}

Notes on parameters:

Setting up a policy file

The test server reads policy to supply to clients from the data directory specified with the --data-dir. The directory contains text files containing protobuf messages that supply the payload to return to the client when it asks for policy. The files are named according to the type of policy requested and the entity the policy is intended for.

User policy

The file names are:

The payload protocol buffer message is CloudPolicySettings. This is generated from policy_templates.json and there is a message field with the name matching the policy name for each supported policy. The value field within the nested message contains the policy value. Here is an example with a few policy settings defined:

HomepageLocation {
  value: "http://www.chromium.org"
}
ShowHomeButton {
  value: true
}

Device policy

The file name is policy_google_chromeos_device.txt and the payload protocol buffer is ChromeDeviceSettingsProto. Example contents:

device_policy_refresh_rate {
  device_policy_refresh_rate: 60
}
user_allowlist {
  user_allowlist: "*@managedchrome.com"
  user_allowlist: "*@gmail.com"
}
device_local_accounts {
  account {
    account_id: "publicsession@managedchrome.com"
    type: ACCOUNT_TYPE_PUBLIC_SESSION
  }
}

Configuring Chromium OS to talk to the test server

In order to do something useful with the test server, you can configure Chromium built for Chromium OS to talk to the test server for device- and user-level policy. Here is what you need to do:

  1. Get a root shell on the VM or Chromebook that you want to talk to the test server.

  2. Make sure you have a writable root file system. Try mount -o remount,rw / if you don't, if that fails, you're likely on an actual device with enabled root file system protection, in that case check out /usr/share/vboot/bin/make_dev_ssd.sh --remove_rootfs_verification

  3. Edit /etc/chrome_dev.conf. Add the following flags:

    --device-management-url=http://<your-ip>:<yourport>
    --enterprise-enrollment-skip-robot-auth
    

    This points the device at your test server and instructs it to skip robot auth setup, which avoids an error during enrollment due to the test server not being able to create robot accounts.

  4. On a shell, say

    restart ui
    
  5. You're now set up to fetch policy from the test server!

Configuring Chromium to talk to the test server

Pass the following command line flag to chrome:

--device-management-url=http://<your-ip>:<yourport>

User policy

To test some user policy setting, configure the policy file as desired and then just log in. The browser should automatically pull policy. You can verify that the policy is correctly pulled down from the server by inspecting [chrome://policy](javascript:void(0);). To test policy changes, you can also just update the policy in the file, and use the "Reload policies" button on [chrome://policy](javascript:void(0);) to refresh policy at runtime.

Device policy

For devices to receive device policy, they need to be enrolled for enterprise management at device setup time. There are some requirements for that to succeed:

To perform the actual enrollment, hit Ctrl+Alt+E on the sign in screen. Provide credentials (note that in case of the test server, you must match the "policy_user" field in your JSON config file) and speak a short prayer. If you get lucky, the device will enroll. Log in and check [chrome://policy](javascript:void(0);) for whether it says device policy is present.