Overview

In this page you will find an explanation on integrating your Azure Active Directory Users data source to Hunters. This table holds information about domain users and their properties, including person-related information.

Supported Data Types

  • Azure AD Users - snapshots of the Azure Active Directory users.

Hunters Ingestion

In order to enable Hunters' ingestion of AAD for your account, you will need to perform several administrative steps as a prerequisite.

Collection Prerequisites

Note: In order to execute all the steps, an Azure admin account is required.

In order to collect the data, you will need to follow the rest of this guide, which is based on the official Microsoft guide.

Register your app

  1. First you need to register your app in azure portal using this page. Important to fill in the Redirect URI field - for example http://localhost:5110. This parameter will be used later on in this guide.
    Here is an example on how the registration process should look like:

     

  2. Now you need to add the User.Read.All permission for your app:

    1. Go to azure Active Directory

    2. On the left sidebar choose App registrations

    3. Choose the app you registered in the previous step.

    4. Go to API permissions on the left sidebar.

    5. Press Add a premission

    6. Choose the Microsoft Graph option

    7. Choose Application premissions option, search for user.read.all and add it.

       

    8. In case you have Not granted for ... Directory alert on the user.read.all permission, you need to press on the Grant admin consent for ... Directory bottom.


      a popup window will pop up -

      choose yes.
      The status for each permission should be changed to  Granted for ... Directory:

       

  3. Add a new client secret to your app:

    1. Go to azure Active Directory

    2. On the left sidebar choose App registrations

    3. Choose the app you registered in the previous step.

    4. Go to Certificates & secrets on the left sidebar.

    5. Press New Client Secret.

    6. After adding the client secret, you will see a new record under Certificates & secrets, its value will be used later in this guid.
      Important: The value of the client secret is only displayed when created, so make sure to write it down and keep it for later use!

Retrieve an Authorization Code

This stage is based on this guide.

  1. Open the browser on which you logged in to the Azure Portal

  2. Paste in the url:
    https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={client_id}&response_type=code&response_mode=query&redirect_uri={redirect_uri}&scope=offline_access%20user.read%20user.read.all

    1. tenant_id - your tenant id, can be found in the portal under tenant properties:

       

    2. client_id - The application id of your registered app. Can be found in:
      Azure Active Directory → App registrations → Under Application (client) ID of your app.

    3. redirect_uri - should be identical to the one you filled when registering your app.

  3. You will be redirected to a new URL, which has the Authorization Code in it (contained in the new URL string as a query parameter), e.g.: look for the code parameter in the URL at the top of browser, in the URL line localhost:5110/?code=<authorization_code>.

Get a Refresh Token

Open terminal and run the following command:
curl -X POST -d 'client_id={client_id}&scope=user.read%20user.read.all&grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_uri}&client_secret={client_secret}' -H "Content-Type: application/x-www-form-urlencoded" https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token

An access token and a refresh token will be returned, Hunters will need the refresh token.

Deliver Keys to Hunters

The parameters needed for Hunters to collect the data are:

  1. tenant_id - your tenant id, can be found in the portal under tenant properties

  2. client_id - The application id of your registered app. Can be found in:
    Azure Active Directory → App registrations → Under Application (client) ID of your app.

  3. client_secret - the value of the client secret you created in step 3 in the Pre collection phase.

  4. refresh_token - The refresh token you retrieved in earlier step.

Expected Format

In case you supply the logs to a shared storage service directly, this is the events' expected format:

{"accountEnabled": true, "city": "LA", "country": "USA", "department": "cyber", "displayName": "Ophir", "employeeId": "1", "givenName": "Ophir", "jobTitle": "solutions", "mail": "ophir@gmail.com", "mailNickname": "ophir", "onPremisesSecurityIdentifier": null, "otherMails": ["op@hir.com"], "passwordPolicies": "policy", "postalCode": "60850", "preferredLanguage": "English", "proxyAddresses": ["127.0.0.1"], "refreshTokensValidFromDateTime": "2022-01-09T13:20:54Z", "showInAddressList": false, "state": "California", "streetAddress": "street", "surname": "Levi", "usageLocation": "USA", "userPrincipalName": "ophir@azure.com", "userType": "Member", "passwordProfile": "profile", "assignedLicenses": ["license"], "assignedPlans": ["plan1", "plan2"], "provisionedPlans": ["plan3", "plan4"]}
CODE

If there is anything unclear or you have any further questions please contact our support 🙂