1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef COMPONENTS_POLICY_CORE_COMMON_CLOUD_CLOUD_POLICY_CLIENT_H_
6 #define COMPONENTS_POLICY_CORE_COMMON_CLOUD_CLOUD_POLICY_CLIENT_H_
14 #include "base/basictypes.h"
15 #include "base/callback.h"
16 #include "base/memory/scoped_ptr.h"
17 #include "base/memory/scoped_vector.h"
18 #include "base/observer_list.h"
19 #include "base/time/time.h"
20 #include "components/policy/core/common/cloud/cloud_policy_constants.h"
21 #include "components/policy/core/common/remote_commands/remote_command_job.h"
22 #include "components/policy/policy_export.h"
23 #include "policy/proto/device_management_backend.pb.h"
26 class URLRequestContextGetter
;
31 class DeviceManagementRequestJob
;
32 class DeviceManagementService
;
34 // Implements the core logic required to talk to the device management service.
35 // Also keeps track of the current state of the association with the service,
36 // such as whether there is a valid registration (DMToken is present in that
37 // case) and whether and what errors occurred in the latest request.
39 // Note that CloudPolicyClient doesn't do any validation of policy responses
40 // such as signature and time stamp checks. These happen once the policy gets
41 // installed in the cloud policy cache.
42 class POLICY_EXPORT CloudPolicyClient
{
44 // Maps a (policy type, settings entity ID) pair to its corresponding
45 // PolicyFetchResponse.
46 using ResponseMap
= std::map
<std::pair
<std::string
, std::string
>,
47 enterprise_management::PolicyFetchResponse
*>;
49 // A callback which receives boolean status of an operation. If the operation
50 // succeeded, |status| is true.
51 using StatusCallback
= base::Callback
<void(bool status
)>;
53 // A callback which receives fetched remote commands.
54 using RemoteCommandCallback
= base::Callback
<void(
55 DeviceManagementStatus
,
56 const std::vector
<enterprise_management::RemoteCommand
>&)>;
58 // Observer interface for state and policy changes.
59 class POLICY_EXPORT Observer
{
63 // Called when a policy fetch completes successfully. If a policy fetch
64 // triggers an error, OnClientError() will fire.
65 virtual void OnPolicyFetched(CloudPolicyClient
* client
) = 0;
67 // Called upon registration state changes. This callback is invoked for
68 // successful completion of registration and unregistration requests.
69 virtual void OnRegistrationStateChanged(CloudPolicyClient
* client
) = 0;
71 // Called when a request for device robot OAuth2 authorization tokens
72 // returns successfully. Only occurs during enrollment. Optional
73 // (default implementation is a noop).
74 virtual void OnRobotAuthCodesFetched(CloudPolicyClient
* client
);
76 // Indicates there's been an error in a previously-issued request.
77 virtual void OnClientError(CloudPolicyClient
* client
) = 0;
80 // |provider| and |service| are weak pointers and it's the caller's
81 // responsibility to keep them valid for the lifetime of CloudPolicyClient.
82 // |verification_key_hash| contains an identifier telling the DMServer which
83 // verification key to use.
85 const std::string
& machine_id
,
86 const std::string
& machine_model
,
87 const std::string
& verification_key_hash
,
88 DeviceManagementService
* service
,
89 scoped_refptr
<net::URLRequestContextGetter
> request_context
);
90 virtual ~CloudPolicyClient();
92 // Sets the DMToken, thereby establishing a registration with the server. A
93 // policy fetch is not automatically issued but can be requested by calling
95 virtual void SetupRegistration(const std::string
& dm_token
,
96 const std::string
& client_id
);
98 // Attempts to register with the device management service. Results in a
99 // registration change or error notification.
100 virtual void Register(
101 enterprise_management::DeviceRegisterRequest::Type registration_type
,
102 enterprise_management::DeviceRegisterRequest::Flavor flavor
,
103 const std::string
& auth_token
,
104 const std::string
& client_id
,
105 const std::string
& requisition
,
106 const std::string
& current_state_key
);
108 // Sets information about a policy invalidation. Subsequent fetch operations
109 // will use the given info, and callers can use fetched_invalidation_version
110 // to determine which version of policy was fetched.
111 void SetInvalidationInfo(int64 version
, const std::string
& payload
);
113 // Requests a policy fetch. The client being registered is a prerequisite to
114 // this operation and this call will CHECK if the client is not in registered
115 // state. FetchPolicy() triggers a policy fetch from the cloud. A policy
116 // change notification is reported to the observers and the new policy blob
117 // can be retrieved once the policy fetch operation completes. In case of
118 // multiple requests to fetch policy, new requests will cancel any pending
119 // requests and the latest request will eventually trigger notifications.
120 virtual void FetchPolicy();
122 // Requests OAuth2 auth codes for the device robot account. The client being
123 // registered is a prerequisite to this operation and this call will CHECK if
124 // the client is not in registered state.
125 virtual void FetchRobotAuthCodes(const std::string
& auth_token
);
127 // Sends an unregistration request to the server.
128 virtual void Unregister();
130 // Upload a device certificate to the server. Like FetchPolicy, this method
131 // requires that the client is in a registered state. |certificate_data| must
132 // hold the X.509 certificate data to be sent to the server. The |callback|
133 // will be called when the operation completes.
134 virtual void UploadCertificate(const std::string
& certificate_data
,
135 const StatusCallback
& callback
);
137 // Uploads device/session status to the server. As above, the client must be
138 // in a registered state. If non-null, |device_status| and |session_status|
139 // will be included in the upload status request. The |callback| will be
140 // called when the operation completes.
141 virtual void UploadDeviceStatus(
142 const enterprise_management::DeviceStatusReportRequest
* device_status
,
143 const enterprise_management::SessionStatusReportRequest
* session_status
,
144 const StatusCallback
& callback
);
146 // Attempts to fetch remote commands, with |last_command_id| being the ID of
147 // the last command that finished execution and |command_results| being
148 // results for previous commands which have not been reported yet. The
149 // |callback| will be called when the operation completes.
150 // Note that sending |last_command_id| will acknowledge this command and any
151 // previous commands. A nullptr indicates that no commands have finished
153 virtual void FetchRemoteCommands(
154 scoped_ptr
<RemoteCommandJob::UniqueIDType
> last_command_id
,
155 const std::vector
<enterprise_management::RemoteCommandResult
>&
157 const RemoteCommandCallback
& callback
);
159 // Sends a device attribute update permission request to the server, uses
160 // OAuth2 token |auth_token| to identify user who requests a permission to
161 // name a device, calls a |callback| from the enrollment screen to indicate
162 // whether the device naming prompt should be shown.
163 void GetDeviceAttributeUpdatePermission(const std::string
& auth_token
,
164 const StatusCallback
& callback
);
166 // Sends a device naming information (Asset Id and Location) to the
167 // device management server, uses OAuth2 token |auth_token| to identify user
168 // who names a device, the |callback| will be called when the operation
170 void UpdateDeviceAttributes(const std::string
& auth_token
,
171 const std::string
& asset_id
,
172 const std::string
& location
,
173 const StatusCallback
& callback
);
175 // Sends a GCM id update request to the DM server. The server will
176 // associate the DM token in authorization header with |gcm_id|, and
177 // |callback| will be called when the operation completes.
178 virtual void UpdateGcmId(const std::string
& gcm_id
,
179 const StatusCallback
& callback
);
181 // Adds an observer to be called back upon policy and state changes.
182 void AddObserver(Observer
* observer
);
184 // Removes the specified observer.
185 void RemoveObserver(Observer
* observer
);
187 void set_submit_machine_id(bool submit_machine_id
) {
188 submit_machine_id_
= submit_machine_id
;
191 void set_last_policy_timestamp(const base::Time
& timestamp
) {
192 last_policy_timestamp_
= timestamp
;
195 void set_public_key_version(int public_key_version
) {
196 public_key_version_
= public_key_version
;
197 public_key_version_valid_
= true;
200 void clear_public_key_version() {
201 public_key_version_valid_
= false;
204 // FetchPolicy() calls will request this policy type.
205 // If |settings_entity_id| is empty then it won't be set in the
206 // PolicyFetchRequest.
207 void AddPolicyTypeToFetch(const std::string
& policy_type
,
208 const std::string
& settings_entity_id
);
210 // FetchPolicy() calls won't request the given policy type and optional
211 // |settings_entity_id| anymore.
212 void RemovePolicyTypeToFetch(const std::string
& policy_type
,
213 const std::string
& settings_entity_id
);
215 // Configures a set of device state keys to transfer to the server in the next
216 // policy fetch. If the fetch is successful, the keys will be cleared so they
217 // are only uploaded once.
218 void SetStateKeysToUpload(const std::vector
<std::string
>& keys
);
220 // Whether the client is registered with the device management service.
221 bool is_registered() const { return !dm_token_
.empty(); }
223 const std::string
& dm_token() const { return dm_token_
; }
224 const std::string
& client_id() const { return client_id_
; }
226 // The device mode as received in the registration request.
227 DeviceMode
device_mode() const { return device_mode_
; }
229 // The policy responses as obtained by the last request to the cloud. These
230 // policies haven't gone through verification, so their contents cannot be
231 // trusted. Use CloudPolicyStore::policy() and CloudPolicyStore::policy_map()
232 // instead for making policy decisions.
233 const ResponseMap
& responses() const {
237 // Returns the policy response for the (|policy_type|, |settings_entity_id|)
238 // pair if found in |responses()|. Otherwise returns nullptr.
239 const enterprise_management::PolicyFetchResponse
* GetPolicyFor(
240 const std::string
& policy_type
,
241 const std::string
& settings_entity_id
) const;
243 DeviceManagementStatus
status() const {
247 const std::string
& robot_api_auth_code() const {
248 return robot_api_auth_code_
;
251 // Returns the invalidation version that was used for the last FetchPolicy.
252 // Observers can call this method from their OnPolicyFetched method to
253 // determine which at which invalidation version the policy was fetched.
254 int64
fetched_invalidation_version() const {
255 return fetched_invalidation_version_
;
258 scoped_refptr
<net::URLRequestContextGetter
> GetRequestContext();
260 // Returns the number of active requests.
261 int GetActiveRequestCountForTest() const;
264 // A set of (policy type, settings entity ID) pairs to fetch.
265 typedef std::set
<std::pair
<std::string
, std::string
>> PolicyTypeSet
;
267 // Callback for retries of registration requests.
268 void OnRetryRegister(DeviceManagementRequestJob
* job
);
270 // Callback for registration requests.
271 void OnRegisterCompleted(
272 DeviceManagementStatus status
,
274 const enterprise_management::DeviceManagementResponse
& response
);
276 // Callback for policy fetch requests.
277 void OnPolicyFetchCompleted(
278 DeviceManagementStatus status
,
280 const enterprise_management::DeviceManagementResponse
& response
);
282 // Callback for robot account api authorization requests.
283 void OnFetchRobotAuthCodesCompleted(
284 DeviceManagementStatus status
,
286 const enterprise_management::DeviceManagementResponse
& response
);
288 // Callback for unregistration requests.
289 void OnUnregisterCompleted(
290 DeviceManagementStatus status
,
292 const enterprise_management::DeviceManagementResponse
& response
);
294 // Callback for certificate upload requests.
295 void OnCertificateUploadCompleted(
296 const DeviceManagementRequestJob
* job
,
297 const StatusCallback
& callback
,
298 DeviceManagementStatus status
,
300 const enterprise_management::DeviceManagementResponse
& response
);
302 // Callback for status upload requests.
303 void OnStatusUploadCompleted(
304 const DeviceManagementRequestJob
* job
,
305 const StatusCallback
& callback
,
306 DeviceManagementStatus status
,
308 const enterprise_management::DeviceManagementResponse
& response
);
310 // Callback for remote command fetch requests.
311 void OnRemoteCommandsFetched(
312 const DeviceManagementRequestJob
* job
,
313 const RemoteCommandCallback
& callback
,
314 DeviceManagementStatus status
,
316 const enterprise_management::DeviceManagementResponse
& response
);
318 // Callback for device attribute update permission requests.
319 void OnDeviceAttributeUpdatePermissionCompleted(
320 const DeviceManagementRequestJob
* job
,
321 const StatusCallback
& callback
,
322 DeviceManagementStatus status
,
324 const enterprise_management::DeviceManagementResponse
& response
);
326 // Callback for device attribute update requests.
327 void OnDeviceAttributeUpdated(
328 const DeviceManagementRequestJob
* job
,
329 const StatusCallback
& callback
,
330 DeviceManagementStatus status
,
332 const enterprise_management::DeviceManagementResponse
& response
);
334 // Callback for gcm id update requests.
336 const DeviceManagementRequestJob
* job
,
337 const StatusCallback
& callback
,
338 DeviceManagementStatus status
,
340 const enterprise_management::DeviceManagementResponse
& response
);
342 // Helper to remove a job from request_jobs_.
343 void RemoveJob(const DeviceManagementRequestJob
* job
);
345 // Observer notification helpers.
346 void NotifyPolicyFetched();
347 void NotifyRegistrationStateChanged();
348 void NotifyRobotAuthCodesFetched();
349 void NotifyClientError();
351 // Data necessary for constructing policy requests.
352 const std::string machine_id_
;
353 const std::string machine_model_
;
354 const std::string verification_key_hash_
;
355 PolicyTypeSet types_to_fetch_
;
356 std::vector
<std::string
> state_keys_to_upload_
;
358 std::string dm_token_
;
359 DeviceMode device_mode_
;
360 std::string client_id_
;
361 bool submit_machine_id_
;
362 base::Time last_policy_timestamp_
;
363 int public_key_version_
;
364 bool public_key_version_valid_
;
365 std::string robot_api_auth_code_
;
367 // Information for the latest policy invalidation received.
368 int64 invalidation_version_
;
369 std::string invalidation_payload_
;
371 // The invalidation version used for the most recent fetch operation.
372 int64 fetched_invalidation_version_
;
374 // Used for issuing requests to the cloud.
375 DeviceManagementService
* service_
;
377 // Only one outstanding policy fetch is allowed, so this is tracked in
378 // its own member variable.
379 scoped_ptr
<DeviceManagementRequestJob
> policy_fetch_request_job_
;
381 // All of the outstanding non-policy-fetch request jobs. These jobs are
382 // silently cancelled if Unregister() is called.
383 ScopedVector
<DeviceManagementRequestJob
> request_jobs_
;
385 // The policy responses returned by the last policy fetch operation.
386 ResponseMap responses_
;
387 DeviceManagementStatus status_
;
389 base::ObserverList
<Observer
, true> observers_
;
390 scoped_refptr
<net::URLRequestContextGetter
> request_context_
;
393 DISALLOW_COPY_AND_ASSIGN(CloudPolicyClient
);
396 } // namespace policy
398 #endif // COMPONENTS_POLICY_CORE_COMMON_CLOUD_CLOUD_POLICY_CLIENT_H_