Export (0) Print
Expand All

Group

Updated: February 23, 2015

Applies To: Azure AD Graph API

Represents an Azure Active Directory group. This topic provides descriptions of the declared properties and navigation properties of the Group entity, as well as the operations, actions, and functions that can be called on a group.

Namespace: Microsoft.WindowsAzure.ActiveDirectory

Base type: DirectoryObject

The Group entity type has the following properties:

Declared Properties

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

description

Edm.String

Optional

Yes

An optional description for the group.

dirSyncEnabled

Edm.Boolean

No

No

Indicates whether this object was synced from the on-premises directory.

displayName

Edm.String

Required

Yes

The display name for the group. This property is required when a group is created and it cannot be cleared during updates.

lastDirSyncTime

Edm.DateTime

No

No

Indicates the last time at which the object was synced with the on-premises directory.

mail

Edm.String

No

No

The SMTP address for the group, for example, "serviceadmins@contoso.onmicrosoft.com".

mailEnabled

Edm.Boolean

Required

Yes

Specifies whether the group is mail-enabled. If the securityEnabled property is also true, the group is a mail-enabled security group; otherwise, the group is a Microsoft Exchange distribution group. Only (pure) security groups can be created using Azure AD Graph. For this reason, the property must be set false when creating a group and it cannot be updated using Azure AD Graph.

mailNickName

Edm.String

Required

Yes

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

objectId

Edm.String

No

No

The unique identifier for the group. Inherited from DirectoryObject.

Notes: key, immutable, not nullable, unique.

objectType

Edm.String

No

No

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

onPremisesSecurityIdentifier

String

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

Notes: Requires version 1.5 or newer.

provisioningErrors

Collection(ProvisioningError)

No

No

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

Notes: not nullable.

proxyAddresses

Collection(Edm.String)

No

No

Notes: not nullable.

securityEnabled

Edm.Boolean

Required

Yes

Specifies whether the group is a security group. If the mailEnabled property is also true, the group is a mail-enabled security group; otherwise it is a security group. Only (pure) security groups can be created using Azure AD Graph. For this reason, the property must be set true when creating a group.

Navigation Properties

Name From Multiplicity To To Multiplicity Description

members

*

DirectoryObject

(Only Contact, Group, and User objects are supported)

*

Users, contacts, and groups that are members of this group. Inherited from DirectoryObject.

HTTP Methods: GET (supported for all groups), POST (supported for security groups and mail-enabled security groups), DELETE (supported only for security groups)

memberOf

*

DirectoryObject

(Only Group objects are supported)

*

Groups that this group is a member of. Inherited from DirectoryObject.

HTTP Methods: GET (supported for all groups)

owners

*

DirectoryObject

*

The owners of the group. The owners are a set of non-admin users who are allowed to modify this object. Requires version 2013-11-08 or newer. Inherited from DirectoryObject.

HTTP Methods: GET (supported for all groups), POST (supported for security groups and mail-enabled security groups), DELETE (supported only for security groups)

appRoleAssignments

*

DirectoryObject

*

Contains the set of applications that a group is assigned to.

Notes: Requires version 1.5 or newer.

extensionProperties

*

DirectoryObject

*

Contains the extension properties associated with the application.

Notes: Requires version 1.5 or newer.

noteNote
Group also inherits the manager and directReports navigation properties from DirectoryObject; however, neither of these properties are valid for groups. If a request for either of these properties 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 group resource set, which spans all the groups in the directory; an individual group; and the navigation properties of a group. 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 (groups)

/groups

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

Individual groups

/groups/{objectId}

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

Navigation property

/groups/{objectId}/$(links)/{property-name}

https://graph.windows.net/contoso.onmicrosoft.com/groups/12345678-9abc-def0-1234-56789abcde/$links/members?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. Groups or their navigation properties can also be addressed as generic directory objects by replacing “groups” with “directoryObjects” in the URL.

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): Supported only for security groups.

  • Read (GET): Supported for all groups.

  • Update (PATCH): Supported only for security groups and mail-enabled security groups. Not all properties can be updated.

  • Delete (DELETE): Supported only for security groups.

The following operations are supported on group navigation properties:

  • Read (GET): Supported for all groups.

  • Update (POST): Supported only for security groups and mail-enabled security groups. (members and owners only.)

  • Delete (DELETE): Supported only for security groups. (members and owners only.)

The following actions and functions may be called on groups:

  • checkMemberGroups to check a group’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 group. Requires version 1.5 or newer.

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

  • isMemberOf to check whether a group 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 privileges to modify group objects to send PATCH, POST, or DELETE requests. It must be in a role that has privileges to read group objects to send GET requests.

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

  • There are three kinds of groups: mail distribution groups (mailEnabled property true and securityEnabled property false); mail-enabled security groups (mailEnabled property true and securityEnabled property true); and, (pure) security groups (mailEnabled property false and securityEnabled property true).

  • You can only create security groups using Azure AD Graph (you cannot create mail-enabled security groups or mail distribution groups). For this reason the mailEnabled property must be set false and the securityEnabled property must be set true when creating a group.

  • All properties marked required must be specified when creating a security group using Azure AD Graph. These properties are: displayName, mailNickName, mailEnabled (false), securityEnabled (true).

  • You cannot update a group from a security group to a mail-enabled security group or to a mail distribution group using Azure AD Graph.

For more information operations on groups including examples, see Operations on Groups.

See Also

Show:
© 2015 Microsoft