Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

User

Updated: May 26, 2015

Important: the content in this topic may be out of date. See the new interactive Graph API documentation for the most up-to-date reference documentation for Azure AD Graph API. With the interactive documentation, you can try REST operations against a sample tenant from inside the documentation itself. Documentation updates are only being made in the interactive documentation, and this topic will be removed in the future.

Applies To: Azure AD Graph API

Represents an Azure AD user account. This topic provides information about the properties and navigation properties exposed by the User entity, as well as the operations, actions, and functions that you can call on it.

Namespace: Microsoft.DirectoryServices for version 1.5 and newer, Microsoft.WindowsAzure.ActiveDirectory for versions prior to 1.5.

Base type: DirectoryObject

The User entity has the following properties:

Declared Properties

Name Type Create (POST) Read (GET) Update (PATCH) Description

accountEnabled

Edm.Boolean

Required

Filterable

Yes

true if the account is enabled; otherwise, false. This property is required when a user is created.

assignedLicenses

Collection(AssignedLicense)

Optional

Yes

The licenses that are assigned to the user.

Notes: not nullable.

assignedPlans

Collection(AssignedPlan)

No

No

The plans that are assigned to the user.

Notes: not nullable.

city

Edm.String

Optional

Filterable

Yes

The city in which the user is located.

country

Edm.String

Optional

Filterable

Yes

The country/region in which the user is located; for example, “US” or “UK”.

deletionTimeStamp

Edm.DateTime

No

No

This property is not valid for users and always returns null. Inherited from DirectoryObject.

Notes: Requires version 1.5 or newer.

department

Edm.String

Optional

Filterable

Yes

The name for the department in which the user works.

dirSyncEnabled

Edm.Boolean

Optional

Filterable

Yes

true if this object was synced from the on-premises directory; otherwise, false.

displayName

Edm.String

Required

Filterable

Yes, but cannot be cleared

The name displayed in the address book for the user. This is usually the combination of the user's first name, middle initial and last name. This property is required when a user is created and it cannot be cleared during updates.

facsimileTelephoneNumber

Edm.String

Optional

Yes

The telephone number of the user's business fax machine.

givenName

Edm.String

Optional

Yes

The given name (first name) of the user.

immutableId

Edm.String

Required if using a federated domain for the UPN

Filterable

Yes

This property is used to associate an on-premises Active Directory user account to their Azure AD user object. This property must be specified when creating a new user account in the Graph if you are using a federated domain for the user’s userPrincipalName (UPN) property.

noteNote
The $ and _ characters cannot be used when specifying this property.

Notes: Requires version 2013-11-08 or newer.

jobTitle

Edm.String

Optional

Filterable

Yes

The user’s job title.

lastDirSyncTime

Edm.DateTime

No

Filterable

Yes

Indicates the last time at which the object was synced with the on-premises directory; for example: "2013-02-16T03:04:54Z"

mail

Edm.String

Optional

Filterable

No

The SMTP address for the user, for example, "jeff@contoso.onmicrosoft.com".

mailNickName

Edm.String

Required

Yes

The mail alias for the user. This property must be specified when a user is created.

mobile

Edm.String

Optional

Yes

The primary cellular telephone number for the user.

objectId

Edm.Guid

No

No

The unique identifier for the user. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.

objectType

Edm.String

No

No

A string that identifies the object type. For users the value is always “User”. Inherited from DirectoryObject.

onPremisesSecurityIdentifier

Edm.String

No

No

Contains the on-premises security identifier (SID) for the user that was synchronized from on-premises to the cloud.

Notes: Requires version 1.5 or newer.

otherMails

Collection(Edm.String)

Optional

Filterable

Yes

A list of additional email addresses for the user; for example: ["bob@contoso.com", "Robert@fabrikam.com"].

Notes: not nullable. When filtering, must be used with the “any” $filter expression.

passwordPolicies

Edm.String

Optional

Yes

Specifies password policies for the user. This value is an enumeration with one possible value being “DisableStrongPassword”, which allows weaker passwords than the default policy to be specified. “DisablePasswordExpiration” can also be specified. The two may be specified together; for example: "DisablePasswordExpiration, DisableStrongPassword".

passwordProfile

PasswordProfile

Required

Yes

Specifies the password profile for the user. The profile contains the user’s password. This property is required when a user is created.

The password in the profile must satisfy minimum requirements as specified by the passwordPolicies property. By default, a strong password is required. For information about the constraints that must be satisfied for a strong password, see Password policy under Change your password in the Microsoft Office 365 help pages.

physicalDeliveryOfficeName

Edm.String

Optional

Yes

The office location in the user's place of business.

postalCode

Edm.String

Optional

Yes

The postal code for the user's postal address. The postal code is specific to the user's country/region. In the United States of America, this attribute contains the ZIP code.

preferredLanguage

Edm.String

Optional

Yes

The preferred language for the user. Should follow ISO 639-1 Code; for example "en-US".

provisionedPlans

Collection(ProvisionedPlan)

No

No

The plans that are provisioned for the user.

Notes: not nullable.

provisioningErrors

Collection(ProvisioningError)

No

No

A collection of error details that are preventing this user from being provisioned successfully.

proxyAddresses

Collection(Edm.String)

No

Filterable

No

Fpr example: ["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]

Notes: unique, not nullable.

sipProxyAddress

Edm.String

No

No

Specifies the voice over IP (VOIP) session initiation protocol (SIP) address for the user.

Notes: Requires version 1.5 or newer.

state

Edm.String

Optional

Filterable

Yes

The state or province in the user's address.

streetAddress

Edm.String

Optional

Yes

The street address of the user's place of business.

surname

Edm.String

Optional

Filterable

Yes

The user's surname (family name or last name).

Notes: filterable.

telephoneNumber

Edm.String

Optional

Yes

The primary telephone number of the user's place of business.

thumbnailPhoto

Edm.Stream

Optional

Yes

A thumbnail photo to be displayed for the user.

Notes: not nullable.

usageLocation

Edm.String

Optional

Filterable

Yes

A two letter country code (ISO standard 3166). Required for users that will be assigned licenses due to legal requirement to check for availability of services in countries. Examples include: "US", "JP", and "GB".

Notes: not nullable.

userPrincipalName

Edm.String

Required

Filterable

Yes

The user principal name (UPN) of the user. The UPN is an Internet-style login name for the user based on the Internet standard RFC 822. By convention, this should map to the user's email name. The general format is alias@domain, where domain must be present in the tenant’s collection of verified domains. This property is required when a user is created.

The verified domains for the tenant can be accessed from the VerifiedDomains property of TenantDetail. For example, for contoso.onmicosoft.com, tenant detail can be read by performing a GET to the following URL: https://graph.windows.net/contoso.onmicrosoft.com/tenantDetails?api-version=1.5.

Notes: key, unique.

userType

Edm.String

Optional

Filterable

Yes

A string value that can be used to classify user types in your directory, such as “Member” and “Guest”.

Notes: Requires version 2013-11-08 or newer.

Navigation Properties

Name From Multiplicity To To Multiplicity Description

manager

*

DirectoryObject

(Only User and Contact objects are supported.)

0..1

The user or contact that is this user’s manager. Inherited from DirectoryObject.

HTTP Methods: GET, PUT, DELETE

directReports

*

DirectoryObject

(Only User and Contact objects are supported.)

*

The users and contacts that report to the user. (The users and contacts that have their manager property set to this user.) Inherited from DirectoryObject.

HTTP Methods: GET

memberOf

*

DirectoryObject

(Only Group and Role objects are supported.)

*

The groups and roles that the user is a member of. Inherited from DirectoryObject.

HTTP Methods: GET

ownedDevices

*

Device

*

Devices that are owned by the user.

permissions

*

Permission

*

The permissions associated with the user. The property is renamed to oauth2PermissionGrants and the Permission entity is renamed to OAuth2PermissionGrant in version 1.5 and newer. See the documentation for OAuth2PermssionGrant for documentation of the Permission entity type.

registeredDevices

*

Device

*

Devices that are registered for the user.

createdObjects

*

DirectoryObject

*

Directory objects that were created by the user. Requires version 2013-11-08 or newer.

ownedObjects

*

DirectoryObject

*

Directory objects that are owned by the user. Requires version 2013-11-08 or newer.

appRoleAssignments

*

AppRoleAssignment

*

The set of applications that this user is assigned to. Requires version 1.5 or newer.

HTTP Methods: GET, POST, DELETE

oauth2PermissionGrants

*

OAuth2PermissionGrant

*

The set of applications that are granted consent to impersonate this user. Requires version 1.5 or newer.

HTTP Methods: GET, POST, DELETE

noteNote
User also inherits additional properties from DirectoryObject; however, this property is not valid for users. If a request for this property is sent, a 400 Bad Request response is returned.

For information about the primitive types exposed by the EDM, see Entity Data Model: Primitive Data Types.

The following table shows how to address the user resource set, which spans all the users in the directory; an individual user; and the navigation properties of a user. Users can be addressed either by Object ID or by their User Principal Name (UPN). The examples in the table use the tenant domain to address the tenant. For other ways of addressing the tenant, see Addressing Entities and Operations in the Graph API.

 

Artifact URL fragment Example

Resource Set (all users)

/users

https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5.

Individual User

/users/{objectId}

-or-

/users/{userPrincipalName}

https://graph.windows.net/contoso.onmicrosoft.com/users/12345678-9abc-def0-1234-56789abcde?api-version=1.5

-or-

https://graph.windows.net/contoso.onmicrosoft.com/users/john@contoso.onmicrosoft.com?api-version=1.5

Navigation Property

/users/{objectId}/$(links)/{property name}

-or-

/users/{userPrincipalName}/$(links)/{property name}

https://graph.windows.net/contoso.onmicrosoft.com/users/12345678-9abc-def0-1234-56789abcde/$links/memberOf?api-version=1.5

-or-

https://graph.windows.net/contoso.onmicrosoft.com/users/John@contoso.onmicrosoft.com/$links/memberOf?api-version=1.5

noteNote
Remove the “$links” segment of the navigation property URL to return the objects referenced by a navigation property rather than links to them. This mode of addressing can be used for read operations only. Users or their navigation properties can also be addressed as generic directory objects by replacing “users” with “directoryObjects” in the URL and specifying the user’s object ID.

For more comprehensive information about querying directory objects, see Azure AD Graph API Common Queries and Azure AD Graph API Differential Query.

The following operations are supported on users (the HTTP method used for each is in parentheses):

  • Create (POST)

  • Read (GET)

  • Update (PATCH)

  • Delete (DELETE)

The following operations are supported on user navigation properties; not all operations are supported on every navigation property.

  • Read (GET)

  • Update (PUT)

  • Delete (DELETE)

The following actions and functions may be called on users:

  • assignUserLicense to assign and/or remove a specified list of licenses from a user. Requires version 2013-11-08 or newer.

  • checkMemberGroups to check the user’s membership in a list of groups. The check is transitive.

  • getAvailableExtensionProperties to return a list of the extension properties that have been registered for a user. Requires version 1.5 or newer.

  • getMemberGroups to return a list of the groups that a user is a member of. The check is transitive.

  • isMemberOf to check whether a user is a member of a specified group. The check is transitive.

The principal that performs the operation must be in an administrator role that has permissions to modify user objects to send PATCH, POST, PUT or DELETE requests or to invoke any action that modifies the user. It must be in a role that has permissions to read user objects to send GET requests or to invoke functions on the user.

See the Remarks section for additional information about performing operations on users.

  • At a minimum, you must specify the following properties when creating a user: accountEnabled, displayName, mailNickName, passwordProfile, and userPrincipalName. The password specified in the passwordProfile property must meet the tenant’s password complexity requirements. For more information, see the passwordPolicies property.

  • In version 2013-11-08 and newer, the immutableId property must be specified when creating a new user account in the Graph if you are using a federated domain for the user’s userPrincipalName (UPN) property.

  • The displayName property cannot be cleared on updates.

  • The passwordProfile property always returns null. This is to prevent the user’s password from being displayed. You can reset the user’s password by updating the passwordProfile property.

  • In addition to the standard addressing available for all directory entities, users may be addressed by using the userPrincipalName property; for example, https://graph.windows.net/contoso.onmicrosoft.com/users/john@contoso.onmicrosoft.com?api-version=1.5.

For more information operations on users including examples, see Operations on Users.

See Also

Show:
© 2015 Microsoft