Skip to content

How to Connect a Mailbox#

This topic provides step-by-step instructions for connecting a mailbox in TheHive.

This is useful when your organization receives alerts via email and you want to automatically convert them into alerts within TheHive.

Required permissions

Only users with an admin-type profile that has the managePlatform permission can manage email intake connectors in TheHive.

Procedure

  1. Go to the Platform management view from the sidebar menu.

    Platform management

  2. Select the Connectors tab.

    Connectors tab

  3. Select the Email intake tab.

    Email intake tab

  4. Enter the time interval between refresh attempts. This setting applies to all connected mailboxes.

    Manual refresh

    If needed, you can also manually trigger an email fetch for a mailbox.

  5. Select .

  6. Configure your email intake connector by following these steps. IMAP configuration is required if your email provider is neither Google nor Microsoft.

    Platinum

    Prerequisites

    You must have administrator access to the Google Cloud Console, with the necessary permissions to create projects and configure OAuth 2.0 credentials.

    Step 1: Create a project in the Google Cloud Console#

    1. Go to the Google Admin Console.

    2. Select APIs & Services.

      Google Cloud Console APIs and services

    3. Select Create project.

      Google Cloud Console Create project

    4. Enter a name for the project, an organization, and a location.

    5. Select Create.

    1. Select OAuth consent screen from the left pane.

      OAuth consent screen

    2. Select Get started to configure Google Auth Platform.

      Google Auth Platform

    3. In the App information section, enter information about your application.

    4. In the Audience section, select Internal.

    5. In the Contact information section, enter the email address that will receive any updates related to the project.

    6. Select Create.

    Step 3: Add a scope in the Google Auth Platform#

    1. Select Data access from the left pane.

      Google Auth Platform Data access

    2. Select Add or remove scopes.

      Google Auth Platform Add remove scopes

    3. In the Manually add scopes section, enter https://mail.google.com/.

    4. Select Add to table.

    5. Make sure the new scope is selected, then select Update.

    6. Make sure the scope is added to the Your restricted scopes section, then select Save.

    Step 4: Create OAuth credentials#

    1. Enter credentials in the search bar at the top of the screen.

    2. Select Credentials from the APIs & Services results.

    3. Select Create credentials, then OAuth Client ID.

      Google Cloud Platform Add credentials

    4. Select Web application as the application type.

    5. Enter an internal name for the OAuth 2.0 client.

    6. Select Add URI in the Authorized JavaScript origins section.

    7. Enter a URI following this format: https://.org.

    8. Enter the same URI in the Authorized redirect URIs section.

    9. Select Create.

    10. Copy the Client ID and Client Secret values from the dialog for use in TheHive configuration.

    Step 5: Configure the email intake connector in TheHive#

    1. Return to your TheHive application.

    2. In the Provider section, enter the following information:

      - Name

      A name for your connector.

      - Provider

      Select Google Workspace from the dropdown.

    3. In the Authentication section, enter the following information:

      - Email

      The email address associated with your account.

      - ClientId

      Paste the Client ID value you obtained from Google.

      - Secret

      Paste the Client Secret value you obtained from Google.

    Then, select Connect to authorize TheHive to access your Google Workspace account for use with the application.

    Platinum

    Prerequisites

    You must have:
    - Administrator access to Microsoft 365.
    - PowerShell installed and properly configured.
    - A shared mailbox already created in Microsoft 365.

    Step 1: Create a mail-enabled security group#

    Create a security group that includes the shared mailbox. This group will be used to restrict access to the application, ensuring it is available only to the shared mailbox.

    1. Go to your Microsoft Exchange admin center.

    2. Follow the Microsoft instructions to create a mail-enabled security group and add the shared mailbox as a member.

    Step 2: Register a new application#

    1. Follow the Microsoft instructions to register an application.

    2. Copy the Application (client) ID and Directory (tenant) ID for use in TheHive configuration.

    Step 3: Add a secret#

    1. Select Certificates & secrets from the left pane.

    2. Follow the Microsoft instructions to add a client secret.

    3. Copy the secret's value for use in TheHive configuration.

      One-time display

      This secret value is never displayed again after you leave this page.

    Step 4: Assign API permissions#

    1. Select API permissions from the left pane.

    2. Follow the Microsoft instructions and add the IMAP.AccessAsApp permission for Office 365 Exchange Online.

    Step 5: Configure PowerShell access#

    1. Define the necessary values for the configuration:

      $AppID = '{ClientID}'
$TenantID = '{TenantID}'
$ObjectID = '{ObjectID}'
$SecurityGroup = '{SecurityGroup}'  # The mail-enabled security group
$MailBox = '{MailBox}'  # The shared mailbox

    2. Run the following PowerShell commands to configure access.

      a. Define app permissions:

      New-ServicePrincipal -AppId $AppID -ServiceId $ObjectID

      b. Grant security group full access to the mailbox:

      Add-MailboxPermission -Identity $MailBox -User $SecurityGroup -AccessRights FullAccess

      c. Restrict access to members of the security group only:

      New-ApplicationAccessPolicy -AppId $AppID -PolicyScopeGroupId $SecurityGroup -AccessRight RestrictAccess -Description "Restrict this app to members of distribution group {$SecurityGroup}"

    3. Test the configuration.

      a. Run the following command to test if the application access policy is properly configured:

      Test-ApplicationAccessPolicy -AppId $AppID -Identity $MailBox

      b. The expected output should be similar to:

      AppId             : 9367xxxx
Mailbox           : test-shared-mailbox20231107190659
AccessCheckResult : Granted

      c. Running the command with a different mailbox should return AccessCheckResult: Denied.

    Step 6: Configure the email intake connector in TheHive#

    1. Return to your TheHive application.

    2. In the Provider section, enter the following information:

      - Name

      A name for your connector.

      - Provider

      Select Microsoft 365 from the dropdown.

    3. In the Authentication section, enter the following information:

      - Email

      The email address associated with your account.

      - TenantId

      Paste the Tenant ID value you obtained from Microsoft.

      - ClientId

      Paste the Client ID value you obtained from Microsoft.

      - Secret

      Paste the Client Secret value you obtained from Microsoft.

    Then, select Connect to authorize TheHive to access your Microsoft 365 account for use with the application.

    5.5 Platinum

    Microsoft Graph API is the recommended standard API for all interactions with Microsoft services.

    Prerequisites

    You must have:
    - Administrator access to Microsoft 365.
    - PowerShell installed and properly configured.
    - A shared mailbox already created in Microsoft 365.

    Step 1: Create a mail-enabled security group#

    Create a security group that includes the shared mailbox. This group will be used to restrict access to the application, ensuring it is available only to the shared mailbox.

    1. Go to your Microsoft Exchange admin center.

    2. Follow the Microsoft instructions to create a mail-enabled security group and add the shared mailbox as a member.

    Step 2: Register a new application#

    1. Follow the Microsoft instructions to register an application.

    2. Copy the Application (client) ID and Directory (tenant) ID for use in TheHive configuration.

    Step 3: Add a secret#

    1. Select Certificates & secrets from the left pane.

    2. Follow the Microsoft instructions to add a client secret.

    3. Copy the secret's value for use in TheHive configuration.

      One-time display

      This secret value is never displayed again after you leave this page.

    Step 4: Assign API permissions#

    1. Select API permissions from the left pane.

    2. Follow the Microsoft instructions to add the relevant permissions.

      Recommanded permissions

      For Microsoft Graph to work correctly with TheHive, ensure that the following permissions are added:

    Step 5: Configure PowerShell access#

    1. Define the necessary values for the configuration:

      $AppID = '{ClientID}'
$TenantID = '{TenantID}'
$ObjectID = '{ObjectID}'
$SecurityGroup = '{SecurityGroup}'  # The mail-enabled security group
$MailBox = '{MailBox}'  # The shared mailbox

    2. Run the following PowerShell commands to configure access.

      a. Define app permissions:

      New-ServicePrincipal -AppId $AppID -ServiceId $ObjectID

      b. Grant security group full access to the mailbox:

      Add-MailboxPermission -Identity $MailBox -User $SecurityGroup -AccessRights FullAccess

      c. Restrict access to members of the security group only:

      New-ApplicationAccessPolicy -AppId $AppID -PolicyScopeGroupId $SecurityGroup -AccessRight RestrictAccess -Description "Restrict this app to members of distribution group {$SecurityGroup}"

    3. Test the configuration.

      a. Run the following command to test if the application access policy is properly configured:

      Test-ApplicationAccessPolicy -AppId $AppID -Identity $MailBox

      b. The expected output should be similar to:

      AppId             : 9367xxxx
Mailbox           : test-shared-mailbox20231107190659
AccessCheckResult : Granted

      c. Running the command with a different mailbox should return AccessCheckResult: Denied.

    Step 6: Configure the email intake connector in TheHive#

    1. Return to your TheHive application.

    2. In the Provider section, enter the following information:

      - Name

      A name for your connector.

      - Provider

      Select Microsoft 365 GraphAPI from the dropdown.

    3. In the Authentication section, enter the following information:

      - Email

      The email address associated with your account.

      - TenantId

      Paste the Tenant ID value you obtained from Microsoft.

      - ClientId

      Paste the Client ID value you obtained from Microsoft.

      - Secret

      Paste the Client Secret value you obtained from Microsoft.

    Then, select Connect to authorize TheHive to access your Microsoft 365 account for use with the application.

    Gold Platinum

    1. In the Provider section, enter the following information:

      - Name

      A name for your connector.

      - Provider

      Select IMAP server from the dropdown.

      - Host

      The host address of the IMAP server.

      - Port

      The port number of the IMAP server.

    2. Add a certificate authority.

      For more information about configuring SSL, refer to the Configure SSL topic.

      Use certificates only from trusted, predefined authorities for secure connections. Custom certificate authorities are not allowed.

      You can turn off the Don't check certificate authority toggle to bypass certificate validation, but this isn't recommended as it may compromise connection security.

    3. Turn on the Disable host name verification toggle if you want to bypass the verification of the server's host name against the certificate.

    4. In the Authentication section, enter the following information:

      - Email

      The email address associated with your account.

      - Password

      The password associated with your account.

  7. In the Settings section, enter the following information:

    - Organization

    The TheHive organization where the alerts are sent.

    - Folder

    The folder from which emails are fetched.

    - Action in mailbox

    The action to perform in the mailbox when receiving an email.

  8. 5.5 In the Alert properties section, enter the following information:

    - Type

    The type of the alerts created through the email intake connector.

    - Source

    The source of the alerts created through the email intake connector.

    - Tags

    The tags to apply to the alerts created through the email intake connector.

  9. Select Test connection to verify your connection.

  10. Select Confirm.

Next steps