Skip to main content

Azure Active Directory Groups

This Integration is part of the Microsoft Graph Groups Pack.#

Azure Active Directory Groups enables you to create and manage different types of groups and group functionality according to your requirements. This integration was integrated and tested with version 1.0 of Microsoft Graph Groups API

Use Cases

  • Manage the organization groups.

Authentication

For more details about the authentication used in this integration, see Microsoft Integrations - Authentication .

Required Permissions

  • Directory.ReadWrite.All - Delegated
  • Directory.ReadWrite.All - Application
  • Group.ReadWrite.All - Application Or GroupMember.ReadWrite.All - Delegation permission

    • Note

    Using "GroupMember.ReadWrite.All" permission instead of Group.ReadWrite.All: This permission allows the app to list groups, read basic properties, and read and update the membership of the groups the signed-in user has access to. Group properties and owners cannot be updated and groups cannot be deleted.
    Using this permission will raise errors on the following commands:
  • msgraph-groups-delete-group
  • msgraph-groups-create-group

    • Configure Azure Active Directory Groups on Cortex XSOAR

  • Manage the organization groups.
    1. Navigate to Settings > Integrations > Servers & Services .
    2. Search for Azure Active Directory Groups.
    3. Click Add instance to create and configure a new integration instance.
      • Name : a textual name for the integration instance.
      • Server URL
      • ID (received from the admin consent - see Detailed Instructions (?)
      • Token (received from the admin consent - see Detailed Instructions (?) section)
      • Key (received from the admin consent - see Detailed Instructions (?)
      • Certificate Thumbprint
      • Private Key
      • Trust any certificate (not secure)
      • Use system proxy settings
    4. Click Test to validate the new instance.

    Commands

    You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

    1. Provides a list of groups: msgraph-groups-list-groups
    2. Returns details of a group: msgraph-groups-get-group
    3. Create a group: msgraph-groups-create-group
    4. Deletes a group: msgraph-groups-delete-group
    5. Lists group members: msgraph-groups-list-members
    6. Add a member to a group: msgraph-groups-add-member
    7. Removes a member from a group: msgraph-groups-remove-member
    8. Generates the login url used for Authorization code flow.: msgraph-groups-generate-login-url

    1. msgraph-groups-list-groups

    Provides a list of groups.

    Base Command

    msgraph-groups-list-groups

    Required Permissions

    The following permissions are required for this command.

    • Directory.ReadWrite.All - Delegated
    • Group.ReadWrite.All - Application
    Input
    Argument Name Description Required
    order_by Sorts groups in an organization by the field values. For example, displayName. Optional
    next_link The URL to the next results page. Optional
    top Sets the page size of the results. Optional
    filter Filters group results. For example, startswith(displayName,'J'), groupTypes/any(c:c+eq+'Unified'). Optional

    Context Output
    Path Type Description
    MSGraphGroups.Classification String A classification for the group (such as low, medium or high business impact).
    MSGraphGroups.CreatedDateTime String The timestamp when the group was created.
    MSGraphGroups.DeletedDateTime String The timestamp when the group was deleted.
    MSGraphGroups.Description String An optional description for the group.
    MSGraphGroups.GroupTypes String Specifies the group type and its membership. If the group collection contains a Unified value, the group is an Office 365 group; otherwise it's a security group. If the collection includes DynamicMembership, the group has dynamic membership; otherwise, membership is static.
    MSGraphGroups.ID String The unique identifier for the group.
    MSGraphGroup.IsAssignableToRole String Whether the group assigned to a specific role.
    MSGraphGroup.Mail String The SMTP address for the group. For example, "serviceadmins@contoso.onmicrosoft.com".
    MSGraphGroup.MailEnabled Boolean Specifies whether the group is mail-enabled.
    MSGraphGroup.MailNickname String The mail alias for the group, which is unique in the organization.
    MSGraphGroup.OnPremisesDomainName String Contains the on-premises domain FQDN. Also called dnsDomainName, which is synchronized from the on-premises directory.
    MSGraphGroup.OnPremisesLastSyncDateTime String Indicates the last time at which the group was synced with the on-premises directory. The Timestamp type represents date and time information using ISO 8601 format in UTC time. For example, midnight UTC on Jan 1, 2019 is '2019-01-01T00:00:00Z'.
    MSGraphGroup.OnPremisesSyncEnabled String Whether this group is synced from an on-premises directory (true). This group was originally synced from an on-premises directory but is no longer synced (false). Null if this object has never been synced from an on-premises directory (default).
    MSGraphGroup.ProxyAddresses String Email addresses for the group that directs to the same group mailbox. For example: ["SMTP: example@demisto.com", "smtp: example@demisto.com"].
    MSGraphGroup.RenewedDateTime String Timestamp of when the group was last renewed, which represents the time and date information using ISO 8601 format. Always in UTC time. For example, midnight UTC on Jan 1, 2019 is '2019-01-01T00:00:00Z'.
    MSGraphGroup.SecurityEnabled Boolean Specifies whether the group is a security group.
    MSGraphGroup.Visibility String Specifies the visibility of an Office 365 group. Can be: "Private", "Public", or "Hiddenmembership". Blank values are treated as public.
    MSGraphGroup.NextLink String The URL of the next results page.

    Command Example

    !msgraph-groups-list-groups top=4

    Context Example 
    {
    "MSGraphGroups": "https://graph.microsoft.com/v1.0/groups?$top=4&$skiptoken={skip_token}"
}
    Human Readable Output

    Groups (Note that there are more results. Please use the next_link argument to see them.):

    ID Display Name Description Created Date Time Mail
    id DemistoTeam DemistoTeam 2019-08-24T09:39:03Z DemistoTeam@demistodev.onmicrosoft.com
    id Graph Groups Test - TEMP 2019-12-04T11:57:29Z
    id TestPublic TestPublic 2018-12-26T09:44:16Z testpublic@demistodev.onmicrosoft.com
    id Graph Groups Test - DELETE 2019-11-17T11:50:59Z

    2. msgraph-groups-get-group

    Returns details of a group.

    Base Command

    msgraph-groups-get-group

    Required Permissions

    The following permissions are required for this command.

    • Directory.ReadWrite.All - Delegated
    • Group.ReadWrite.All - Application
    Input
    Argument Name Description Required
    group_id The ID of the group. Required

    Context Output
    Path Type Description
    MSGraphGroups.Classification String A classification for the group (such as low, medium or high business impact).
    MSGraphGroups.CreatedDateTime String The timestamp when the group was created.
    MSGraphGroups.DeletedDateTime String The timestamp when the group was deleted.
    MSGraphGroups.Description String An optional description for the group.
    MSGraphGroups.GroupTypes String Specifies the group type and its membership. If the group collection contains a Unified value, the group is an Office 365 group; otherwise it's a security group. If the collection includes DynamicMembership, the group has dynamic membership; otherwise, membership is static.
    MSGraphGroups.ID String The unique identifier for the group.
    MSGraphGroup.IsAssignableToRole String Whether the group assigned to a specific role.
    MSGraphGroup.Mail String The SMTP address for the group. For example, "serviceadmins@contoso.onmicrosoft.com".
    MSGraphGroup.MailEnabled Boolean Specifies whether the group is mail-enabled.
    MSGraphGroup.MailNickname String The mail alias for the group, unique in the organization.
    MSGraphGroup.OnPremisesDomainName String Contains the on-premises domain FQDN. Also called dnsDomainName, which is synchronized from the on-premises directory.
    MSGraphGroup.OnPremisesLastSyncDateTime String Indicates the last time at which the group was synced with the on-premises directory.The Timestamp type represents date and time information using ISO 8601 format in UTC time. For example, midnight UTC on Jan 1, 2019 is '2019-01-01T00:00:00Z'.
    MSGraphGroup.OnPremisesSyncEnabled String Whether the group is synced from an on-premises directory (true). This group was originally synced from an on-premises directory but is no longer synced (false). Null if this object has never been synced from an on-premises directory (default).
    MSGraphGroup.ProxyAddresses String Email addresses for the group that directs to the same group mailbox. For example: ["SMTP: example@demisto.com", "smtp: example@demisto.com"].
    MSGraphGroup.RenewedDateTime String The timestamp of when the group was last renewed. This cannot be modified directly and is only updated via the renew service action. The Timestamp type represents date and time information using ISO 8601 format in UTC time. For example, midnight UTC on Jan 1, 2019 is '2019-01-01T00:00:00Z'.
    MSGraphGroup.SecurityEnabled Boolean Specifies whether the group is a security group.
    MSGraphGroup.Visibility String Specifies the visibility of an Office 365 group. Possible values are: Private, Public, or Hiddenmembership. Blank values are treated as public.

    Command Example

    !msgraph-groups-get-group group_id={group_id}

    Context Example 
    {
    "MSGraphGroups": {
        "Classification": null,
        "CreatedDateTime": "2019-08-24T09:39:03Z",
        "DeletedDateTime": null,
        "Description": "DemistoTeam",
        "DisplayName": "DemistoTeam",
        "GroupTypes": [
            "Unified"
        ],
        "ID": "id",
        "IsAssignableToRole": null,
        "Mail": "DemistoTeam@demistodev.onmicrosoft.com",
        "MailEnabled": true,
        "MailNickname": "DemistoTeam",
        "OnPremisesDomainName": null,
        "OnPremisesLastSyncDateTime": null,
        "OnPremisesSyncEnabled": null,
        "ProxyAddresses": [
            "SPO:spo",
            "SMTP:DemistoTeam@demistodev.onmicrosoft.com"
        ],
        "RenewedDateTime": "2019-11-07T11:40:09Z",
        "SecurityEnabled": false,
        "Visibility": "Public"
    }
}
    Human Readable Output

    Groups:

    ID Display Name Description Created Date Time Mail Security Enabled Visibility
    id DemistoTeam DemistoTeam 2019-08-24T09:39:03Z DemistoTeam@demistodev.onmicrosoft.com false Public

    3. msgraph-groups-create-group

    Create a group.

    Base Command

    msgraph-groups-create-group

    Required Permissions

    The following permissions are required for this command.

    • Directory.ReadWrite.All - Delegated
    • Group.ReadWrite.All - Application
    Input
    Argument Name Description Required
    display_name The display name of the group. Required
    mail_enabled Set to true for mail-enabled groups. False for groups without an email. Optional
    mail_nickname The mail alias for the group. Required
    security_enabled Set to true for security groups. False for non security groups (regular groups). Required

    Context Output
    Path Type Description
    MSGraphGroups.Classification String A classification for the group (such as low, medium or high business impact).
    MSGraphGroups.CreatedDateTime String The timestamp when the group was created.
    MSGraphGroups.DeletedDateTime String The timestamp when the group was deleted.
    MSGraphGroups.Description String An optional description for the group.
    MSGraphGroups.GroupTypes String Specifies the group type and its membership. If the group collection contains a Unified value, the group is an Office 365 group; otherwise it's a security group. If the group collection includes DynamicMembership, the group has dynamic membership; otherwise, membership is static.
    MSGraphGroups.ID String The unique identifier for the group.
    MSGraphGroup.IsAssignableToRole String Whether the group is assigned to a specific role.
    MSGraphGroup.Mail String The SMTP address for the group. For example, "serviceadmins@contoso.onmicrosoft.com".
    MSGraphGroup.MailEnabled Boolean Specifies whether the group is mail-enabled.
    MSGraphGroup.MailNickname String The mail alias for the group, unique in the organization.
    MSGraphGroup.OnPremisesDomainName String Contains the on-premises domain FQDN. Also called dnsDomainName, which is synchronized from the on-premises directory.
    MSGraphGroup.OnPremisesLastSyncDateTime String Indicates the last time at which the group was synced with the on-premises directory.The Timestamp type represents date and time information using ISO 8601 format in UTC time. For example, midnight UTC on Jan 1, 2019 is '2019-01-01T00:00:00Z'.
    MSGraphGroup.OnPremisesSyncEnabled String Whether this group is synced from an on-premises directory (true). This group was originally synced from an on-premises directory but is no longer synced (false). Null if this object has never been synced from an on-premises directory (default).
    MSGraphGroup.ProxyAddresses String Email addresses for the group that directs to the same group mailbox. For example, ["SMTP: example@demisto.com", "smtp: example@demisto.com"].
    MSGraphGroup.RenewedDateTime String Timestamp of when the group was last renewed. This cannot be modified directly and is only updated via the renew service action. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'.
    MSGraphGroup.SecurityEnabled Boolean Specifies whether the group is a security group.
    MSGraphGroup.Visibility String Specifies the visibility of an Office 365 group. Possible values are: Private, Public, or Hiddenmembership; blank values are treated as public.

    Command Example

    !msgraph-groups-create-group display_name="Graph Groups Test - TEMP" mail_nickname="Test_Group_101" security_enabled="true"

    Context Example 
    {
    "MSGraphGroups": {
        "Classification": null,
        "CreatedDateTime": "2019-12-04T11:59:44Z",
        "DeletedDateTime": null,
        "Description": null,
        "DisplayName": "Graph Groups Test - TEMP",
        "GroupTypes": [],
        "ID": "id",
        "IsAssignableToRole": null,
        "Mail": null,
        "MailEnabled": false,
        "MailNickname": "Test_Group_101",
        "OnPremisesDomainName": null,
        "OnPremisesLastSyncDateTime": null,
        "OnPremisesSyncEnabled": null,
        "ProxyAddresses": [],
        "RenewedDateTime": "2019-12-04T11:59:44Z",
        "SecurityEnabled": true,
        "Visibility": null
    }
}
    Human Readable Output

    Graph Groups Test - TEMP was created successfully:

    ID Display Name Created Date Time Security Enabled Mail Enabled
    id Graph Groups Test - TEMP 2019-12-04T11:59:44Z true false

    4. msgraph-groups-delete-group

    Deletes a group.

    Base Command

    msgraph-groups-delete-group

    Required Permissions

    The following permissions are required for this command.

    • Directory.ReadWrite.All - Delegated
    • Group.ReadWrite.All - Application
    Input
    Argument Name Description Required
    group_id The group ID. Required

    Context Output
    Path Type Description
    MSGraphGroups.ID String The unique identifier for the group.
    MSGraphGroup.Deleted Boolean Specifies whether the group was deleted.

    Command Example

    !msgraph-groups-delete-group group_id="id"

    Human Readable Output

    5. msgraph-groups-list-members

    Lists group members.

    Base Command

    msgraph-groups-list-members

    Required Permissions

    The following permissions are required for this command.

    • Directory.ReadWrite.All - Delegated
    • Group.ReadWrite.All - Application
    Input
    Argument Name Description Required
    group_id The group ID. Required
    next_link The URL for the next results page. Optional
    top Sets the page size of results. Optional
    filter Filters members results. For example, startswith(displayName,'user'). Optional
    count Retrieves the total count of matching resources. Optional

    Context Output
    Path Type Description
    MSGraphGroups.Members.BussinessPhones String The telephone numbers for the user.
    MSGraphGroups.Members.GivenName String The given name (first name) of the user.
    MSGraphGroups.Members.MobilePhone String The primary mobile telephone number for the user.
    MSGraphGroups.Members.DisplayName String The name displayed in the address book for the user. Usually the combination of the user's first name, middle initial and last name.
    MSGraphGroups.Members.UserPrincipalName Unknown 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 the domain must be present in the tenant’s collection of verified domains.
    MSGraphGroups.Members.OfficeLocation String The office location in the user's place of business.
    MSGraphGroups.Members.Mail String The SMTP address for the user. For example, "jeff@contoso.onmicrosoft.com".
    MSGraphGroups.Members.PreferredLanguage String The preferred language for the user. Should follow ISO 639-1 Code. For example, "en-US".
    MSGraphGroups.Members.Surname String The user's surname (family name or last name).
    MSGraphGroups.Members.JobTitle String The user’s job title.
    MSGraphGroups.Members.ID String The unique identifier for the user.

    Command Example

    !msgraph-groups-list-members group_id=id

    Context Example 
    {
    "MSGraphGroups": {
        "Classification": null,
        "CreatedDateTime": "2019-08-24T09:39:03Z",
        "DeletedDateTime": null,
        "Description": "DemistoTeam",
        "DisplayName": "DemistoTeam",
        "GroupTypes": [
            "Unified"
        ],
        "ID": "id",
        "IsAssignableToRole": null,
        "Mail": "DemistoTeam@demistodev.onmicrosoft.com",
        "MailEnabled": true,
        "MailNickname": "DemistoTeam",
        "Members": [
            {
                "BusinessPhones": [],
                "DisplayName": "name",
                "GivenName": "name",
                "ID": "id",
                "JobTitle": "test",
                "Mail": "name@demistodev.onmicrosoft.com",
                "MobilePhone": null,
                "OfficeLocation": null,
                "PreferredLanguage": "en-US",
                "Surname": "name",
                "UserPrincipalName": "name@demistodev.onmicrosoft.com"
            },
        ],
        "OnPremisesDomainName": null,
        "OnPremisesLastSyncDateTime": null,
        "OnPremisesSyncEnabled": null,
        "ProxyAddresses": [
            "SPO:spo",
            "SMTP:DemistoTeam@demistodev.onmicrosoft.com"
        ],
        "RenewedDateTime": "2019-11-07T11:40:09Z",
        "SecurityEnabled": false,
        "Visibility": "Public"
    }
}
    Human Readable Output

    Group {group_id} members:

    ID Display Name Job Title Mail
    id name test name@demistodev.onmicrosoft.com

    6. msgraph-groups-add-member

    Add a member to a group.

    Base Command

    msgraph-groups-add-member

    Required Permissions

    The following permissions are required for this command.

    • Directory.ReadWrite.All - Delegated
    • Group.ReadWrite.All - Application
    Input
    Argument Name Description Required
    group_id The group ID. Required
    user_id The user ID. Required

    Context Output
    There are no context output for this command.

    Command Example

    !msgraph-groups-add-member group_id="id" user_id="id"

    Context Example 
    {}
    Human Readable Output

    User {user_id} was added to the Group {group_id} successfully.

    7. msgraph-groups-remove-member

    Removes a member from a group.

    Base Command

    msgraph-groups-remove-member

    Required Permissions

    The following permissions are required for this command.

    • Directory.ReadWrite.All - Delegated
    • Group.ReadWrite.All - Application
    Input
    Argument Name Description Required
    group_id The group ID. Required
    user_id The user ID. Required

    Context Output
    There are no context output for this command.

    Command Example

    !msgraph-groups-remove-member group_id="id" user_id="id"

    Context Example 
    {}
    Human Readable Output

    User {user_id} was removed from the Group {group_id} successfully.

    8. msgraph-groups-auth-reset

    Run this command if for some reason you need to rerun the authentication process.

    Base Command

    msgraph-groups-auth-reset

    Input

    There are no input arguments for this command.

    Context Output
    There are no context output for this command.

    Additional Information

    Troubleshooting

    Known Limitations

    As per , Microsoft also supports dynamic distribution groups which cannot be managed or retrieved through Microsoft Graph.

    Edit this page
    Report an Issue