Microsoft Graph User

Use the Microsoft Graph integration to connect to and interact with user objects on Microsoft Platforms. This integration was integrated and tested with Microsoft Graph v1.0.

Authentication

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

Required Permissions

  • Directory.Read.All - Delegated
  • User.ReadWrite.All - Application
  • User.Read - Delegated
  • Configure Microsoft Graph User on Cortex XSOAR

    1. Navigate to Settings > Integrations > Servers & Services .
    2. Search for Microsoft Graph User.
    3. Click Add instance to create and configure a new integration instance.
      • Name : a textual name for the integration instance.
      • Host URL (e.g., https://graph.microsoft.com )
      • ID you received from the admin consent
      • Key you received from the admin consent
      • Token you received from the admin consent
      • Trust any certificate (not secure)
      • Use system proxy settings
    4. Click Test to validate the URLs, token, and connection.

    Commands

    You can execute these commands from the Demisto 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. Terminate a user session


    Terminates a user’s session from all Office 365 applications, and prevents sign in. Can only work with a self-deployed application and the permission: Directory.AccessAsUser.All(Delegated)

    Base Command

    msgraph-user-terminate-session

    Input
    Argument Name Description Required
    user User ID or userPrincipalName. Required

    Context Output

    There is no context output for this command.

    Command Example
    msgraph-user-terminate-session user="oren@demistodev.onmicrosoft.com"
    Human Readable Output

    user: "oren@demistodev.onmicrosoft.com " session has been terminated successfully

    2. Unblock a user


    Unblocks a user.

    Base Command

    msgraph-user-unblock

    Input
    Argument Name Description Required
    user User ID or userPrincipalName. Required

    Context Output

    There is no context output for this command.

    Command Example
    msgraph-user-unblock user="ore@demistdev.onmicrosoft.com"
    Human Readable Output

    "ore@demistdev.onmicrosoft.com " unblocked. It might take several minutes for the changes to take affect across all applications.

    3. Update properties of a user object


    Updates the properties of a user object.

    Base Command

    msgraph-user-update

    Input
    Argument Name Description Required
    user User ID or userPrincipalName for which to update properties. Required
    updated_fields User fields to update (in JSON format). Required

    Context Output
    Path Type Description
    MSGraphUser.ID String User’s ID.
    MSGraphUser.DisplayName String User’s display name.
    MSGraphUser.GivenName String User’s given name.
    MSGraphUser.BusinessPhones String User’s business phone numbers.
    MSGraphUser.JobTitle String User’s job title.
    MSGraphUser.Mail String User’s mail address.
    MSGraphUser.MobilePhone String User’s mobile phone number.
    MSGraphUser.OfficeLocation String User’s office location.
    MSGraphUser.PreferredLanguage String User’s preferred language.
    MSGraphUser.Surname String User’s surname.
    MSGraphUser.UserPrincipalName String User’s principal name.

    Command Example
    msgraph-user-update user="graph@demistodev.onmicrosoft.com" updated_fields="mobilePhone=050505050"
    Context Example
    {
        "MSGraphUser": {
            "Surname": null, 
            "DisplayName": "Graph Test - DELETE", 
            "MobilePhone": "050505050", 
            "PreferredLanguage": null, 
            "JobTitle": "Test", 
            "UserPrincipalName": "graph@demistodev.onmicrosoft.com", 
            "OfficeLocation": null, 
            "BusinessPhones": [], 
            "Mail": null, 
            "GivenName": null, 
            "ID": "57a820e9-90bc-4692-a22e-27bd170699cb"
        }
    }
    
    Human Readable Output

    graph@demistodev.onmicrosoft.com data

    Display Name Job Title Mobile Phone User Principal Name ID
    Graph Test - DELETE Test 050505050 graph@demistodev.onmicrosoft.com 57a820e9-90bc-4692-a22e-27bd170699cb

    4. Delete a user


    Deletes an existing user.

    Base Command

    msgraph-user-delete

    Input
    Argument Name Description Required
    user User ID or userPrincipalName to delete. Required

    Context Output

    There is no context output for this command.

    Command Example
    msgraph-user-delete user="graph@demistodev.onmicrosoft.com"
    Human Readable Output

    user: "graph@demistodev.onmicrosoft.com" was deleted successfully

    5. Create a user


    Creates a new user.

    Base Command

    msgraph-user-create

    Input
    Argument Name Description Required
    account_enabled If "true", the account is enabled. If "false", the account is disabled. Optional
    display_name The name to display in the address book. Required
    on_premises_immutable_id Only needs to be specified when creating a new user account if you are using a federated domain for the user’s userPrincipalName (UPN) property. Optional
    mail_nickname The mail alias for the user. Required
    password The password profile for the user. Required
    user_principal_name The user principal name, for example: foo@test.com. Required
    other_properties Optional properties for the user, for example: “displayName=name,mobilePhone=phone-num”. Optional

    Context Output
    Path Type Description
    MSGraphUser.ID String User’s ID.
    MSGraphUser.DisplayName String User’s display name.
    MSGraphUser.GivenName String User’s given name.
    MSGraphUser.BusinessPhones String User’s business phone numbers.
    MSGraphUser.JobTitle String User’s job title.
    MSGraphUser.Mail String User’s mail address.
    MSGraphUser.MobilePhone String User’s mobile phone number.
    MSGraphUser.OfficeLocation String User’s office location.
    MSGraphUser.PreferredLanguage String User’s preferred language.
    MSGraphUser.Surname String User’s surname.
    MSGraphUser.UserPrincipalName String User’s principal name.

    Command Example
    msgraph-user-create display_name="Graph Test - DELETE" mail_nickname="graph" password="Aa123456" user_principal_name="graph@demistodev.onmicrosoft.com" other_properties="jobTitle=Test,city=Tel Aviv"
    Context Example
    {
        "MSGraphUser": {
            "Surname": null, 
            "DisplayName": "Graph Test - DELETE", 
            "MobilePhone": null, 
            "PreferredLanguage": null, 
            "JobTitle": "Test", 
            "UserPrincipalName": "graph@demistodev.onmicrosoft.com", 
            "OfficeLocation": null, 
            "BusinessPhones": [], 
            "Mail": null, 
            "GivenName": null, 
            "ID": "57a820e9-90bc-4692-a22e-27bd170699cb"
        }
    }
    
    Human Readable Output

    graph@demistodev.onmicrosoft.com was created successfully:

    Display Name Job Title User Principal Name ID
    Graph Test - DELETE Test graph@demistodev.onmicrosoft.com 57a820e9-90bc-4692-a22e-27bd170699cb

    6. Get new, updated, or deleted user information


    Deprecated. This command only returns a single page. Use the msgraph-user-list command instead, which gets newly created, updated, or deleted users without performing a full read of the entire user collection.

    Base Command

    msgraph-user-get-delta

    Input
    Argument Name Description Required
    properties A CSV list of properties by which to filter the results, for example: “displayName,jobTitle,mobilePhone”. Optional

    Context Output
    Path Type Description
    MSGraphUser.ID String User’s ID.
    MSGraphUser.DisplayName String User’s display name.
    MSGraphUser.GivenName String User’s given name.
    MSGraphUser.BusinessPhones String User’s business phone numbers.
    MSGraphUser.JobTitle String User’s job title.
    MSGraphUser.Mail String User’s mail address.
    MSGraphUser.MobilePhone String User’s mobile phone.
    MSGraphUser.OfficeLocation String User’s office location.
    MSGraphUser.PreferredLanguage String User’s preferred language.
    MSGraphUser.Surname String User’s surname.
    MSGraphUser.UserPrincipalName String User’s principal name.

    Command Example
    msgraph-user-get-delta properties="mobilePhone"
    Context Example
    {
        "MSGraphUser": [
            {
                "ID": "2827c1e7-edb6-4529-b50d-25984e968637", 
                "UserPrincipalName": "dev@demisto.works"
            }, 
            {
                "ID": "c788ab51-6b4f-42cc-8b50-0759a8701c0b", 
                "UserPrincipalName": "donaldt@demistodev.onmicrosoft.com"
            }, 
            {
                "UserPrincipalName": "test@demistodev.onmicrosoft.com", 
                "ID": "00df702c-cdae-460d-a442-46db6cecca29", 
                "MobilePhone": "*********"
            }, 
            {
                "Status": "deleted", 
                "ID": "28a1b242-4737-4bb8-a855-a9519d8e6a28"
            }, 
        ]
    }
    
    Human Readable Output

    All Graph Users

    Mobile Phone ID User Principal Name
    1245678900 670edadc-0197-45b0-90e6-ee061e25ab73 test2@demistodev.onmicrosoft.com
    0525399092 00df702c-cdae-460d-a442-46db6cecca29 ore@demisodev.onmicrosoft.com

    7. Get user object information


    Retrieves the properties and relationships of user objects. For more information, see the Microsoft Graph User documentation .

    Base Command

    msgraph-user-get

    Input
    Argument Name Description Required
    user User ID or userPrincipalName. Required
    properties A CSV list of properties by which to filter the results, for example: “displayName,jobTitle,mobilePhone”. Optional

    Context Output
    Path Type Description
    MSGraphUser.ID String User’s ID.
    MSGraphUser.DisplayName String User’s display name.
    MSGraphUser.GivenName String User’s given name.
    MSGraphUser.BusinessPhones String User’s business phone numbers.
    MSGraphUser.JobTitle String User’s job title.
    MSGraphUser.Mail String User’s mail address.
    MSGraphUser.MobilePhone String User’s mobile phone number.
    MSGraphUser.OfficeLocation String User’s office location.
    MSGraphUser.PreferredLanguage String User’s preferred language.
    MSGraphUser.Surname String User’s surname.
    MSGraphUser.UserPrincipalName String User’s principal name.

    Command Example
    msgraph-user-get user="graph@demistodev.onmicrosoft.com"
    Context Example
    {
        "MSGraphUser": {
            "Surname": null, 
            "DisplayName": "Graph Test - DELETE", 
            "MobilePhone": null, 
            "PreferredLanguage": null, 
            "JobTitle": "Test", 
            "UserPrincipalName": "graph@demistodev.onmicrosoft.com", 
            "OfficeLocation": null, 
            "BusinessPhones": [], 
            "Mail": null, 
            "GivenName": null, 
            "ID": "57a820e9-90bc-4692-a22e-27bd170699cb"
        }
    }
    
    Human Readable Output

    graph@demistodev.onmicrosoft.com data

    Display Name Job Title User Principal Name ID
    Graph Test - DELETE Test graph@demistodev.onmicrosoft.com 57a820e9-90bc-4692-a22e-27bd170699cb

    8. Get a list of user objects


    Retrieves a list of user objects.

    Base Command

    msgraph-user-list

    Input
    Argument Name Description Required
    properties A CSV list of properties by which to filter the results, for example: “displayName,jobTitle,mobilePhone”. Optional
    next_page The URL for the next page in the list. Optional

    Context Output
    Path Type Description
    MSGraphUser.ID String User’s ID.
    MSGraphUser.DisplayName String User’s display name.
    MSGraphUser.GivenName String User’s given name.
    MSGraphUser.BusinessPhones String User’s business phone numbers.
    MSGraphUser.JobTitle String User’s job title.
    MSGraphUser.Mail String User’s mail address.
    MSGraphUser.MobilePhone String User’s mobile phone number.
    MSGraphUser.OfficeLocation String User’s office location.
    MSGraphUser.PreferredLanguage String User’s preferred language.
    MSGraphUser.Surname String User’s surname.
    MSGraphUser.UserPrincipalName String User’s principal name.
    MSGraphUser.NextPage string A token pass to the next list command to retrieve additional results.

    Command Example
    msgraph-user-list properties="id,userPrincipalName"
    Context Example
    {
        "MSGraphUser": [
            {
                "ID": "2827c1e7-edb6-4529-b50d-25984e968637", 
                "UserPrincipalName": "dev@demisto.works"
            }, 
            {
                "ID": "c788ab51-6b4f-42cc-8b50-0759a8701c0b", 
                "UserPrincipalName": "donaldt@demistodev.onmicrosoft.com"
            }, 
            {
                "ID": "57a820e9-90bc-4692-a22e-27bd170699cb", 
                "UserPrincipalName": "graph@demistodev.onmicrosoft.com"
            }
        ]
    }
    
    Human Readable Output

    All Graph Users

    ID User Principal Name
    2827c1e7-edb6-4529-b50d-25984e968637 dev@demisto.works
    c788ab51-6b4f-42cc-8b50-0759a8701c0b donaldt@demistodev.onmicrosoft.com
    57a820e9-90bc-4692-a22e-27bd170699cb graph@demistodev.onmicrosoft.com

    9. Get the direct reports of a user.


    Retrieves the direct reports for a user. Direct reports are the people who have that user configured as their manager.

    Base Command

    msgraph-direct-reports

    Input
    Argument Name Description Required
    user The User ID or userPrincipalName of the user for which to retrieve direct reports. Required

    Context Output
    Path Type Description
    MSGraphUserDirectReports.Manager String The manager's user principal name (UPN).
    MSGraphUserDirectReports.Reports.@Odata.Type String A string value that can be used to classify user types in your directory, such as "Member" and "Guest".
    MSGraphUserDirectReports.Reports.DisplayName String 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.
    MSGraphUserDirectReports.Reports.GivenName String The given name (first name) of the user.
    MSGraphUserDirectReports.Reports.ID String The user ID in Microsoft Graph User.
    MSGraphUserDirectReports.Reports.JobTitle String The user's job title.
    MSGraphUserDirectReports.Reports.Mail String The email address of the user.
    MSGraphUserDirectReports.Reports.MobilePhone String The primary cellular telephone number for the user.
    MSGraphUserDirectReports.Reports.OfficeLocation String The office location in the user's place of business.
    MSGraphUserDirectReports.Reports.PreferredLanguage String The preferred language for the user. Should follow ISO 639-1 Code; for example: en-US.
    MSGraphUserDirectReports.Reports.Surname String The user's surname (family name or last name).
    MSGraphUserDirectReports.Reports.UserPrincipalName String 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 organization.

    Command Example
    msgraph-direct-reports user="graph@demistodev.onmicrosoft.com"
    Context Example
    {
        "MSGraphUserDirectReports": {
            "Manager": "graph@demistodev.onmicrosoft.com",
            "Reports": [
                {
                    "@Odata.Type": "#microsoft.graph.user",
                    "BusinessPhones": [],
                    "DisplayName": "oren",
                    "GivenName": null,
                    "ID": "8c7327ec-0c8e-4ac0-900b-7791199e7bc3",
                    "JobTitle": null,
                    "Mail": "oren@demistodev.onmicrosoft.com",
                    "MobilePhone": null,
                    "OfficeLocation": null,
                    "PreferredLanguage": null,
                    "Surname": null,
                    "UserPrincipalName": "oren@demistodev.onmicrosoft.com"
                }
            ]
        }
    }
    
    Human Readable Output

    graph@demistodev.onmicrosoft.com - direct reports

    @Odata.Type Display Name ID Mail User Principal Name
    #microsoft.graph.user oren 8c7327ec-0c8e-4ac0 -900b-7791199e7bc3 oren@demistodev. onmicrosoft.com oren@demistodev. onmicrosoft.com

    10. Get the manager of a user.


    Retrieves the properties from the manager of a user.

    Base Command

    msgraph-user-get-manager

    Input
    Argument Name Description Required
    user The User ID or userPrincipalName of the user for which to get the manager. Required

    Context Output
    Path Type Description
    MSGraphUserManager.ID String User's ID.
    MSGraphUserManager.Manager.ID String Managers user's ID.
    MSGraphUserManager.Manager.DisplayName String User's display name.
    MSGraphUserManager.Manager.GivenName String User's given name.
    MSGraphUserManager.Manager.BusinessPhones String User's business phone numbers.
    MSGraphUserManager.Manager.JobTitle String User's job title.
    MSGraphUserManager.Manager.Mail String User's mail address.
    MSGraphUserManager.Manager.MobilePhone String User's mobile phone number.
    MSGraphUserManager.Manager.OfficeLocation String User's office location.
    MSGraphUserManager.Manager.PreferredLanguage String User's preferred language.
    MSGraphUserManager.Manager.Surname String User's surname.
    MSGraphUserManager.Manager.UserPrincipalName String User's principal name.
    MSGraphUserManager.Manager.@Odata.Type String A string value that can be used to classify user types in your directory, such as "Member" and "Guest".

    Command Example
    msgraph-user-get-manager user="oren@demistodev.onmicrosoft.com"
    Context Example
    {
        "MSGraphUserManager": {
            "Manager": {
                "@Odata.Type": "#microsoft.graph.user",
                "BusinessPhones": [],
                "DisplayName": "Graph Test - DELETE",
                "GivenName": null,
                "ID": "8c7327ec-0c8e-4ac0-900b-7791199e7bc3",
                "JobTitle": null,
                "Mail": "graph@demistodev.onmicrosoft.com",
                "MobilePhone": null,
                "OfficeLocation": null,
                "PreferredLanguage": null,
                "Surname": null,
                "UserPrincipalName": "graph@demistodev.onmicrosoft.com"
            },
            "User": "oren@demistodev.onmicrosoft.com"
        }
    }
    
    Human Readable Output

    oren@demistodev.onmicrosoft.com - manager

    @Odata.Type Display Name ID Mail User Principal Name
    #microsoft.graph.user Graph Test - DELETE 8c7327ec-0c8e-4ac0-900b- 7791199e7bc3 graph@demistodev. onmicrosoft.com graph@demistodev. onmicrosoft.com

    11. Assign a manager to a user.


    Assigns a manager to the user.

    Base Command

    msgraph-user-assign-manager

    Input
    Argument Name Description Required
    user User ID or userPrincipalName of the user to assign a manager for. Required
    manager User ID or userPrincipalName of the manager. Required

    Context Output

    There is no context output for this command.

    Command Example
    msgraph-user-assign-manager user="oren@demistodev.onmicrosoft.com" manager="graph@demistodev.onmicrosoft.com"
    Human Readable Output

    A manager was assigned to user "oren@demistodev.onmicrosoft.com". It might take several minutes for the changes to take affect across all applications.

    9. Changes the user password


    Changes the user password. Can only work with a self-deployed application and the permission: Directory.AccessAsUser.All(Delegated)

    Base Command

    msgraph-user-change-password

    Input
    Argument Name Description Required
    password The new password. Required
    force_change_password_next_sign_in Whether the password will be changed on the next sign in. Optional
    force_change_password_with_mfa Whether to change the password with MFA. Optional
    Human Readable Output

    user: {user_id} password was changed successfully.