1 /*
2  * Copyright (C) 2021 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.app.admin;
18 
19 import static java.util.Objects.requireNonNull;
20 
21 import android.accounts.Account;
22 import android.annotation.NonNull;
23 import android.annotation.Nullable;
24 import android.annotation.SystemApi;
25 import android.content.ComponentName;
26 import android.os.Bundle;
27 import android.os.Parcel;
28 import android.os.Parcelable;
29 import android.os.PersistableBundle;
30 import android.stats.devicepolicy.DevicePolicyEnums;
31 
32 /**
33  * Params required to provision a managed profile, see
34  * {@link DevicePolicyManager#createAndProvisionManagedProfile}.
35  *
36  * @hide
37  */
38 @SystemApi
39 public final class ManagedProfileProvisioningParams implements Parcelable {
40     private static final String LEAVE_ALL_SYSTEM_APPS_ENABLED_PARAM =
41             "LEAVE_ALL_SYSTEM_APPS_ENABLED";
42     private static final String ORGANIZATION_OWNED_PROVISIONING_PARAM =
43             "ORGANIZATION_OWNED_PROVISIONING";
44     private static final String ACCOUNT_TO_MIGRATE_PROVIDED_PARAM = "ACCOUNT_TO_MIGRATE_PROVIDED";
45     private static final String KEEP_MIGRATED_ACCOUNT_PARAM = "KEEP_MIGRATED_ACCOUNT";
46 
47     @NonNull private final ComponentName mProfileAdminComponentName;
48     @NonNull private final String mOwnerName;
49     @Nullable private final String mProfileName;
50     @Nullable private final Account mAccountToMigrate;
51     private final boolean mLeaveAllSystemAppsEnabled;
52     private final boolean mOrganizationOwnedProvisioning;
53     private final boolean mKeepAccountOnMigration;
54     @NonNull private final PersistableBundle mAdminExtras;
55 
ManagedProfileProvisioningParams( @onNull ComponentName profileAdminComponentName, @NonNull String ownerName, @Nullable String profileName, @Nullable Account accountToMigrate, boolean leaveAllSystemAppsEnabled, boolean organizationOwnedProvisioning, boolean keepAccountOnMigration, @NonNull PersistableBundle adminExtras)56     private ManagedProfileProvisioningParams(
57             @NonNull ComponentName profileAdminComponentName,
58             @NonNull String ownerName,
59             @Nullable String profileName,
60             @Nullable Account accountToMigrate,
61             boolean leaveAllSystemAppsEnabled,
62             boolean organizationOwnedProvisioning,
63             boolean keepAccountOnMigration,
64             @NonNull PersistableBundle adminExtras) {
65         this.mProfileAdminComponentName = requireNonNull(profileAdminComponentName);
66         this.mOwnerName = requireNonNull(ownerName);
67         this.mProfileName = profileName;
68         this.mAccountToMigrate = accountToMigrate;
69         this.mLeaveAllSystemAppsEnabled = leaveAllSystemAppsEnabled;
70         this.mOrganizationOwnedProvisioning = organizationOwnedProvisioning;
71         this.mKeepAccountOnMigration = keepAccountOnMigration;
72         this.mAdminExtras = adminExtras;
73     }
74 
75     /**
76      * Returns the profile owner's {@link ComponentName}.
77      */
78     @NonNull
getProfileAdminComponentName()79     public ComponentName getProfileAdminComponentName() {
80         return mProfileAdminComponentName;
81     }
82 
83     /**
84      * Returns the profile owner's name.
85      */
86     @NonNull
getOwnerName()87     public String getOwnerName() {
88         return mOwnerName;
89     }
90 
91     /**
92      * Returns the profile's name if set, otherwise returns {@code null}.
93      */
94     @Nullable
getProfileName()95     public String getProfileName() {
96         return mProfileName;
97     }
98 
99     /**
100      * If set, it returns the {@link Account} to migrate from the parent profile to the managed
101      * profile after provisioning, otherwise returns {@code null}.
102      */
103     @Nullable
getAccountToMigrate()104     public Account getAccountToMigrate() {
105         return mAccountToMigrate;
106     }
107 
108     /**
109      * Returns {@code true} if system apps should be left enabled after provisioning.
110      */
isLeaveAllSystemAppsEnabled()111     public boolean isLeaveAllSystemAppsEnabled() {
112         return mLeaveAllSystemAppsEnabled;
113     }
114 
115     /**
116      * Returns {@code true} if this is an org owned device.
117      */
isOrganizationOwnedProvisioning()118     public boolean isOrganizationOwnedProvisioning() {
119         return mOrganizationOwnedProvisioning;
120     }
121 
122     /**
123      * Returns {@code true} if the migrated account from {@link #getAccountToMigrate()} should be
124      * kept in parent profile.
125      */
isKeepingAccountOnMigration()126     public boolean isKeepingAccountOnMigration() {
127         return mKeepAccountOnMigration;
128     }
129 
130     /**
131      * Returns a copy of the admin extras bundle.
132      *
133      * @see DevicePolicyManager#EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE
134      */
getAdminExtras()135     public @NonNull PersistableBundle getAdminExtras() {
136         return new PersistableBundle(mAdminExtras);
137     }
138 
139     /**
140      * Logs the provisioning params using {@link DevicePolicyEventLogger}.
141      *
142      * @hide
143      */
logParams(@onNull String callerPackage)144     public void logParams(@NonNull String callerPackage) {
145         requireNonNull(callerPackage);
146 
147         logParam(callerPackage, LEAVE_ALL_SYSTEM_APPS_ENABLED_PARAM, mLeaveAllSystemAppsEnabled);
148         logParam(callerPackage, ORGANIZATION_OWNED_PROVISIONING_PARAM,
149                 mOrganizationOwnedProvisioning);
150         logParam(callerPackage, KEEP_MIGRATED_ACCOUNT_PARAM, mKeepAccountOnMigration);
151         logParam(callerPackage, ACCOUNT_TO_MIGRATE_PROVIDED_PARAM,
152                 /* value= */ mAccountToMigrate != null);
153     }
154 
logParam(String callerPackage, String param, boolean value)155     private void logParam(String callerPackage, String param, boolean value) {
156         DevicePolicyEventLogger
157                 .createEvent(DevicePolicyEnums.PLATFORM_PROVISIONING_PARAM)
158                 .setStrings(callerPackage)
159                 .setAdmin(mProfileAdminComponentName)
160                 .setStrings(param)
161                 .setBoolean(value)
162                 .write();
163     }
164 
165     /**
166      * Builder class for {@link ManagedProfileProvisioningParams} objects.
167      */
168     public static final class Builder {
169         @NonNull private final ComponentName mProfileAdminComponentName;
170         @NonNull private final String mOwnerName;
171         @Nullable private String mProfileName;
172         @Nullable private Account mAccountToMigrate;
173         private boolean mLeaveAllSystemAppsEnabled;
174         private boolean mOrganizationOwnedProvisioning;
175         private boolean mKeepingAccountOnMigration;
176         @Nullable private PersistableBundle mAdminExtras;
177 
178         /**
179          * Initialize a new {@link Builder) to construct a {@link ManagedProfileProvisioningParams}.
180          * <p>
181          * See {@link DevicePolicyManager#createAndProvisionManagedProfile}
182          *
183          * @param profileAdminComponentName The admin {@link ComponentName} to be set as the profile
184          * owner.
185          * @param ownerName The name of the profile owner.
186          *
187          * @throws NullPointerException if {@code profileAdminComponentName} or
188          * {@code ownerName} are null.
189          */
Builder( @onNull ComponentName profileAdminComponentName, @NonNull String ownerName)190         public Builder(
191                 @NonNull ComponentName profileAdminComponentName, @NonNull String ownerName) {
192             requireNonNull(profileAdminComponentName);
193             requireNonNull(ownerName);
194             this.mProfileAdminComponentName = profileAdminComponentName;
195             this.mOwnerName = ownerName;
196         }
197 
198         /**
199          * Sets the profile name of the created profile when
200          * {@link DevicePolicyManager#createAndProvisionManagedProfile} is called. Defaults to
201          * {@code null} if not set.
202          */
203         @NonNull
setProfileName(@ullable String profileName)204         public Builder setProfileName(@Nullable String profileName) {
205             this.mProfileName = profileName;
206             return this;
207         }
208 
209         /**
210          * Sets the {@link Account} to migrate from the parent profile to the created profile when
211          * {@link DevicePolicyManager#createAndProvisionManagedProfile} is called. If not set, or
212          * set to {@code null}, no accounts will be migrated.
213          */
214         @NonNull
setAccountToMigrate(@ullable Account accountToMigrate)215         public Builder setAccountToMigrate(@Nullable Account accountToMigrate) {
216             this.mAccountToMigrate = accountToMigrate;
217             return this;
218         }
219 
220         /**
221          * Sets whether non-required system apps should be installed on
222          * the created profile when {@link DevicePolicyManager#createAndProvisionManagedProfile}
223          * is called. Defaults to {@code false} if not set.
224          */
225         @NonNull
setLeaveAllSystemAppsEnabled(boolean leaveAllSystemAppsEnabled)226         public Builder setLeaveAllSystemAppsEnabled(boolean leaveAllSystemAppsEnabled) {
227             this.mLeaveAllSystemAppsEnabled = leaveAllSystemAppsEnabled;
228             return this;
229         }
230 
231         /**
232          * Sets if this device is owned by an organization. Defaults to {@code false}
233          * if not set.
234          */
235         @NonNull
setOrganizationOwnedProvisioning(boolean organizationOwnedProvisioning)236         public Builder setOrganizationOwnedProvisioning(boolean organizationOwnedProvisioning) {
237             this.mOrganizationOwnedProvisioning = organizationOwnedProvisioning;
238             return this;
239         }
240 
241         /**
242          * Sets whether to keep the account on the parent profile during account migration.
243          * Defaults to {@code false}.
244          */
245         @NonNull
setKeepingAccountOnMigration(boolean keepingAccountOnMigration)246         public Builder setKeepingAccountOnMigration(boolean keepingAccountOnMigration) {
247             this.mKeepingAccountOnMigration = keepingAccountOnMigration;
248             return this;
249         }
250 
251         /**
252          * Sets a {@link Bundle} that contains admin-specific extras.
253          */
254         @NonNull
255         //TODO(b/235783053) The adminExtras parameter is actually @Nullable.
setAdminExtras(@onNull PersistableBundle adminExtras)256         public Builder setAdminExtras(@NonNull PersistableBundle adminExtras) {
257             mAdminExtras = adminExtras != null
258                     ? new PersistableBundle(adminExtras)
259                     : new PersistableBundle();
260             return this;
261         }
262 
263         /**
264          * Combines all of the attributes that have been set on this {@code Builder}.
265          *
266          * @return a new {@link ManagedProfileProvisioningParams} object.
267          */
268         @NonNull
build()269         public ManagedProfileProvisioningParams build() {
270             return new ManagedProfileProvisioningParams(
271                     mProfileAdminComponentName,
272                     mOwnerName,
273                     mProfileName,
274                     mAccountToMigrate,
275                     mLeaveAllSystemAppsEnabled,
276                     mOrganizationOwnedProvisioning,
277                     mKeepingAccountOnMigration,
278                     mAdminExtras != null ? mAdminExtras : new PersistableBundle());
279         }
280     }
281 
282     @Override
describeContents()283     public int describeContents() {
284         return 0;
285     }
286 
287     /**
288      * @hide
289      */
290     @Override
toString()291     public String toString() {
292         return "ManagedProfileProvisioningParams{"
293                 + "mProfileAdminComponentName=" + mProfileAdminComponentName
294                 + ", mOwnerName=" + mOwnerName
295                 + ", mProfileName=" + (mProfileName == null ? "null" : mProfileName)
296                 + ", mAccountToMigrate=" + (mAccountToMigrate == null ? "null" : mAccountToMigrate)
297                 + ", mLeaveAllSystemAppsEnabled=" + mLeaveAllSystemAppsEnabled
298                 + ", mOrganizationOwnedProvisioning=" + mOrganizationOwnedProvisioning
299                 + ", mKeepAccountOnMigration=" + mKeepAccountOnMigration
300                 + ", mAdminExtras=" + mAdminExtras
301                 + '}';
302     }
303 
304     @Override
writeToParcel(@onNull Parcel dest, @Nullable int flags)305     public void writeToParcel(@NonNull Parcel dest, @Nullable int flags) {
306         dest.writeTypedObject(mProfileAdminComponentName, flags);
307         dest.writeString(mOwnerName);
308         dest.writeString(mProfileName);
309         dest.writeTypedObject(mAccountToMigrate, flags);
310         dest.writeBoolean(mLeaveAllSystemAppsEnabled);
311         dest.writeBoolean(mOrganizationOwnedProvisioning);
312         dest.writeBoolean(mKeepAccountOnMigration);
313         dest.writePersistableBundle(mAdminExtras);
314     }
315 
316     public static final @NonNull Creator<ManagedProfileProvisioningParams> CREATOR =
317             new Creator<ManagedProfileProvisioningParams>() {
318                 @Override
319                 public ManagedProfileProvisioningParams createFromParcel(Parcel in) {
320                     ComponentName componentName = in.readTypedObject(ComponentName.CREATOR);
321                     String ownerName = in.readString();
322                     String profileName = in.readString();
323                     Account account = in.readTypedObject(Account.CREATOR);
324                     boolean leaveAllSystemAppsEnabled = in.readBoolean();
325                     boolean organizationOwnedProvisioning = in.readBoolean();
326                     boolean keepAccountMigrated = in.readBoolean();
327                     PersistableBundle adminExtras = in.readPersistableBundle();
328 
329                     return new ManagedProfileProvisioningParams(
330                             componentName,
331                             ownerName,
332                             profileName,
333                             account,
334                             leaveAllSystemAppsEnabled,
335                             organizationOwnedProvisioning,
336                             keepAccountMigrated,
337                             adminExtras);
338                 }
339 
340                 @Override
341                 public ManagedProfileProvisioningParams[] newArray(int size) {
342                     return new ManagedProfileProvisioningParams[size];
343                 }
344             };
345 }
346