1<!--
2  Copyright (C) 2020 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# Users for system developers
18
19## Concepts
20
21### Users and profiles
22
23#### User
24
25A user is a representation of a person using a device, with their own distinct application data
26and some unique settings. Throughout this document, the word 'user' will be used in this technical
27sense, i.e. for this virtual environment, whereas the word 'person' will be used to denote an actual
28human interacting with the device.
29
30Each user has a separate [`userId`](#int-userid).
31
32#### Profile Group
33
34Often, there is a 1-to-1 mapping of people who use a device to 'users'; e.g. there may be two users
35on a device - the owner and a guest, each with their own separate home screen.
36
37However, Android also supports multiple profiles for a single person, e.g. one for their private
38life and one for work, both sharing a single home screen.
39Each profile in a profile group is a distinct user, with a unique [`userId`](#int-userid), and have
40a different set of apps and accounts,
41but they share a single UI, single launcher, and single wallpaper.
42All profiles of a profile group can be active at the same time.
43
44You can list the profiles of a user via `UserManager#getEnabledProfiles` (you usually don't deal
45with disabled profiles)
46
47#### Parent user
48
49The main user of a profile group, to which the other profiles of the group 'belong'.
50This is usually the personal (as opposed to work) profile. Get this via
51`UserManager#getProfileParent` (returns `null` if the user does not have profiles).
52
53#### Profile (Managed profile)
54
55A profile of the parent user, i.e. a profile belonging to the same profile group as a parent user,
56with whom they share a single home screen.
57Currently, the only type of profile supported in AOSP is a 'Managed Profile'.
58The name comes from the fact that these profiles are usually
59managed by a device policy controller app. You can create a managed profile from within the device
60policy controller app on your phone.
61
62Note that, as a member of the profile group, the parent user may sometimes also be considered a
63'profile', but generally speaking, the word 'profile' denotes a user that is subordinate to a
64parent.
65
66#### Foreground user vs background user
67
68Only a single user can be in the foreground.
69This is the user with whom the person using the device is currently interacting, or, in the case
70of profiles, the parent profile of this user.
71All other running users are background users.
72Some users may not be running at all, neither in the foreground nor the background.
73
74#### Account
75
76An account of a user with a (usually internet based) service. E.g. aname@gmail.com or
77aname@yahoo.com. Each user can have multiple accounts. A user does not have to have a
78account.
79
80#### System User
81
82The user with [`userId`](#int-userid) 0 denotes the system user, which is always required to be
83running.
84
85On most devices, the system user is also used by the primary person using the device; however,
86on certain types of devices, the system user may be a stand-alone user, not intended for direct
87human interaction.
88
89## Data types
90
91### int userId
92
93The id of a user. List all users via `adb shell dumpsys user`.
94In code, these are sometimes marked as `@UserIdInt`.
95
96### int uid
97
98Identity of an app. This is the same as a Linux uid, but in Android there is one uid per package,
99per user.
100
101It is highly discouraged, but uids can be shared between multiple packages using the
102`android:sharedUserId` manifest attribute.
103
104### class UserHandle
105
106A wrapper for userId. Used esp. in public APIs instead of `int userId` as it clearly distinguishes
107from uid.
108
109## Security model
110
111Multiple packages can share an uid by using `android:sharedUserId` manifest attribute. If packages
112share a uid they can run in the same process via `android:process` manifest attribute. Further file
113level access is also tracked by uid. Hence any security or privacy mechanism needs to be built on
114a uid granularity.
115
116On the other hand apps belonging to the same user cannot see each others files. They can only
117interact via activity launches, broadcasts, providers, and service bindings. All of them can be be
118protected by [permissions](../permission/Permissions.md). Hence any new general communication
119mechanism should be access controlled by permissions.
120
121## Lifecycle
122
123A system service should deal with users being started and stopped by overriding
124`SystemService.onSwitchUser` and `SystemService.onStopUser`.
125
126If a user become inactive the system should stop all apps of this user from interacting
127with other apps or the system.
128
129Another important lifecycle event is `onUnlockUser`. Only for an unlocked user can you access
130all data, e.g. which packages are installed.
131
132You only want to deal with user profiles that
133
134- are in the profile group of the foreground user
135- the user profile is unlocked and not yet stopped
136