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 unknown User’s ID.
    MSGraphUser.DisplayName unknown User’s display name.
    MSGraphUser.GivenName unknown User’s given name.
    MSGraphUser.BusinessPhones unknown User’s business phone numbers.
    MSGraphUser.JobTitle unknown User’s job title.
    MSGraphUser.Mail unknown User’s mail address.
    MSGraphUser.MobilePhone unknown User’s mobile phone number.
    MSGraphUser.OfficeLocation unknown User’s office location.
    MSGraphUser.PreferredLanguage unknown User’s preferred language.
    MSGraphUser.Surname unknown User’s surname.
    MSGraphUser.UserPrincipalName unknown 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 unknown User’s ID.
    MSGraphUser.DisplayName unknown User’s display name.
    MSGraphUser.GivenName unknown User’s given name.
    MSGraphUser.BusinessPhones unknown User’s business phone numbers.
    MSGraphUser.JobTitle unknown User’s job title.
    MSGraphUser.Mail unknown User’s mail address.
    MSGraphUser.MobilePhone unknown User’s mobile phone number.
    MSGraphUser.OfficeLocation unknown User’s office location.
    MSGraphUser.PreferredLanguage unknown User’s preferred language.
    MSGraphUser.Surname unknown User’s surname.
    MSGraphUser.UserPrincipalName unknown 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 unknown User’s ID.
    MSGraphUser.DisplayName unknown User’s display name.
    MSGraphUser.GivenName unknown User’s given name.
    MSGraphUser.BusinessPhones unknown User’s business phone numbers.
    MSGraphUser.JobTitle unknown User’s job title.
    MSGraphUser.Mail unknown User’s mail address.
    MSGraphUser.MobilePhone unknown User’s mobile phone.
    MSGraphUser.OfficeLocation unknown User’s office location.
    MSGraphUser.PreferredLanguage unknown User’s preferred language.
    MSGraphUser.Surname unknown User’s surname.
    MSGraphUser.UserPrincipalName unknown 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 unknown User’s ID.
    MSGraphUser.DisplayName unknown User’s display name.
    MSGraphUser.GivenName unknown User’s given name.
    MSGraphUser.BusinessPhones unknown User’s business phone numbers.
    MSGraphUser.JobTitle unknown User’s job title.
    MSGraphUser.Mail unknown User’s mail address.
    MSGraphUser.MobilePhone unknown User’s mobile phone number.
    MSGraphUser.OfficeLocation unknown User’s office location.
    MSGraphUser.PreferredLanguage unknown User’s preferred language.
    MSGraphUser.Surname unknown User’s surname.
    MSGraphUser.UserPrincipalName unknown 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 unknown User’s ID.
    MSGraphUser.DisplayName unknown User’s display name.
    MSGraphUser.GivenName unknown User’s given name.
    MSGraphUser.BusinessPhones unknown User’s business phone numbers.
    MSGraphUser.JobTitle unknown User’s job title.
    MSGraphUser.Mail unknown User’s mail address.
    MSGraphUser.MobilePhone unknown User’s mobile phone number.
    MSGraphUser.OfficeLocation unknown User’s office location.
    MSGraphUser.PreferredLanguage unknown User’s preferred language.
    MSGraphUser.Surname unknown User’s surname.
    MSGraphUser.UserPrincipalName unknown 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

    Screen Shot 2019-04-24 at 12 13 05

    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.