# Configuring Mimecast for Log Collection via API

Configuring Mimecast for Log Collection via API

You must complete the following to successfully configure and verify your Mimecast log collector:

1. Set up the Mimecast application
2. Configure collection
3. Verify successful configuration

### 1. Set up the Mimecast application <a href="#application" id="application"></a>

You must identify your regional base URL, enable enhanced logging, add a custom API application, create a new user profile and application setting, and generate API access and secret Keys in the Mimecast administrator portal.

#### Identify your base domain URL <a href="#url" id="url"></a>

Copy and paste the [base URL](https://integrations.mimecast.com/documentation/api-overview/global-base-urls/) for your host region in a safe place for later.

#### Enable enhanced logging for your account

You must enable the log API endpoint in the Mimecast console.

1. Log into the Administration Console.
2. Go to **Administration > Account > Account Settings** menu.
3. Click the **Enhanced Logging** section.
4. Enable the log type(s) you would like to get by using the BluSapphire Mimecast collector.

For more information on enabling the log endpoint, see [SIEM log API endpoint](https://integrations.mimecast.com/documentation/endpoint-reference/logs-and-statistics/get-siem-logs/). For a description of Mimecast SIEM logs, see [Understanding SIEM Logs](https://integrations.mimecast.com/documentation/tutorials/understanding-siem-logs/).

#### Add a custom API application for integration with BluSapphire <a href="#addacustomapiapplicationforintegrationwi" id="addacustomapiapplicationforintegrationwi"></a>

You must [add an API application](https://community.mimecast.com/s/article/Managing-API-Applications-505230018) in the Mimecast console. This procedure creates an Application ID and Application Key that you target when you configure the Mimecast collector later in the BluSapphire later.

1. Log into the Administration Console.
2. Navigate to the **Administration | Services | API and Platform Integrations** menu.
3. Click the **Your Application Integrations** tab.
4. Click **Add API Application**.
5. In the details section, provide the following information:
   * **Application Name**— Name of your BluSapphire Integration. Example: "BluSapphire Log Collector"
   * **Category**— SIEM Integration
   * Select the **Enable Extended Session** option so that the access keys generated for the application do not expire based on the Authentication Profile's Authentication TTL value. This option prevents interruptions to the BluSapphire Mimecast collector.
   * **Description**— Provide an additional description of the integration. For example, "Our cybersecurity Managed Detection and Response (MDR) provider"
6. Click **Next**.
7. In the settings section, provide the following information:
   * Developer: BluSapphire
   * Email: <info@blusapphire.com>
8. Click **Next**.
9. Verify the information in the Summary page.
10. Click **Add**.
11. Copy and paste the **Application ID** and **Application Key** in a safe place for later.

#### Create a user profile for the BluSapphire integration <a href="#createauserprofileforalertlogicintegrati" id="createauserprofileforalertlogicintegrati"></a>

You must create a user profile with the correct permissions to generate API keys for Mimecast collector [authentication](https://integrations.mimecast.com/documentation/api-overview/authentication-scripts-server-apps/).

**To create a new user:**

1. Log into the Administration Console.
2. Navigate to the **Administration | Directories | Internal Directories** menu.
3. Click the internal domain you want for your new user, which is used to get API keys later.
4. Click **New Address** and complete the form to create a new user.
5. Copy and paste the user name and password in a safe place for later.

**To add the user to the administrative role:**

1. Navigate to the **Administration | Account | Roles** menu.
2. Right-click the **Basic Administrator** role and click **Add users to role**.
3. Select the new user that you created.
4. Click **Add Selected Users**.

**To create a new group to add your users:**

1. Navigate to the **Administration | Directories | Profile Groups** menu.
2. Click the **+** icon on a parent directory to create a new child group directory named "New Folder." If you aren't sure which parent directory to add the group under, use **Root**. To edit the name, click the group and change the name in the text box. Example: "BluSapphire Logs Admin"
3. Click the **Build** tab, and then click **Add Email Addresses**.
4. Enter the email address of the new user that you created. Click **Save and Exit**.

**To create a new authentication profile:**

1. Navigate to the **Administration | Services | Applications** menu.
2. Click the **Authentication Profiles** tab.
3. Click **New Authentication Profile**.
4. In the **Description** field, enter a name for your new profile. Example: "API Authentication Profile for the BluSapphire Log collector."
5. On the **Authentication TTL** dropdown menu, click **Never Expires**.
6. Leave the other settings as default.
7. Click **Save and Exit**.

**To create a new application setting:**

You must create a new application setting to bind the user group, authentication profile, and custom API application to each other.

1. Navigate to the **Administration | Services | Applications** menu.
2. Click the **New Application Settings** tab.
3. Click **New Authentication Profile**.
4. In the **Description** field, enter a name for your new setting. Example: "API Application Setting for the BluSapphire Log collector."
5. In the **Group** field, paste the group you created.
6. In the **Authentication Profile** field, select the authentication profile you created.
7. Click **Save and Exit**.

**Troubleshooting:** If you receive an error during this step, you must reach out to Mimecast customer service to perform a workaround that only Super Administrator users and Mimecast employees can perform.

### Get your authentication token

Now that you have a dedicated user who will receive an Authentication Token that will never expire, the final preparation task is to get the Authentication Token for the user.

### Get an Authentication token using Windows

**NOTE:** This process has been tested in Powershell version 4 and 5.

1. Copy paste the following script into a Powershell window: <br>

$appId = Read-Host -Prompt 'Input your registered application id'

$creds = Get-Credential

$discoverPostBody = @{"data" = ,@{"emailAddress" = $creds.UserName}}

$discoverPostBodyJson = ConvertTo-Json $discoverPostBody

$discoverRequestId = \[GUID]::NewGuid().guid

$discoverRequestHeaders = @{"x-mc-app-id" = $appId; "x-mc-req-id" = $discoverRequestId; "Content-Type" = "application/json"}

$discoveryData = Invoke-RestMethod -Method Post -Headers $discoverRequestHeaders -Body $discoverPostBodyJson -Uri "[**https://api.mimecast.com/api/login/discover-authentication**](https://api.mimecast.com/api/login/discover-authentication)"

$baseUrl = $discoveryData.data.region.api

$keys = @{}

$uri = $baseUrl + "/api/login/login"

$requestId = \[GUID]::NewGuid()

$netCred = $creds.GetNetworkCredential()

$PlainPassword = $netCred.Password

$credsBytes = \[System.Text.Encoding]::ASCII.GetBytes($creds.UserName + ":" + $PlainPassword)

$creds64 = \[System.Convert]::ToBase64String($credsBytes)

$headers = @{"Authorization" = "Basic-Cloud " + $creds64; "x-mc-app-id" = $appId; "x-mc-req-id" = $requestId; "Content-Type" = "application/json"}

$postBody = @{"data" = ,@{"username" = $creds.UserName}}

$postBodyJson = ConvertTo-Json $postBody

$data = Invoke-RestMethod -Method Post -Headers $headers -Body $postBodyJson -Uri $uri

"Meta: " + $data.meta

"Access key: " + $data.data.accessKey

"Secret key: " + $data.data.secretKey

"Fail: " + $data.fail.errorss

1. When prompted, enter the Application ID value received when you registered your application.
2. Enter the email address and password of the user created in Step 1: Create a new user into the Windows credentials box that will launch after you have pasted the script into the Powershell window.
3. Copy and paste the **accessKey** and **secretKey** values printed at the bottom of the Powershell window to use in your application.

   **IMPORTANT:** be sure to copy and paste these values to a text editor and remove any line breaks caused by your Powershell window size before using the values.

### Getting an Authentication token using Mac OSX or \*nix systems

1. Open a terminal application and type the following command to generate a base64 encoded string of your administrators email address and password:

**echo -n 'email\_address:password' | openssl base64**

Where **email\_address** is the email address of the user created in Step 1 and **password** is the password created for the user in Step 1. Be sure to include the ":" between the email\_address and password as authentication will fail without it.

1. Type the following command to use cURL to login to the Mimecast API and get your Authentication Token.

**curl -i -H 'Authorization**: Basic-Cloud base64\_encoded\_username\_password' -H 'x-mc-app-id: app\_id' -H 'Content-Type:application/json' <https://xx-api.mimecast.com/api/login/login> --data-binary '{"data":\[{"username": "email\_address"}]}'

Where:

**base64\_encoded\_username\_password** is the value generated in step 1.\
**app\_id** is your Application ID value received when you registered your application.\
**xx-api** is the base url for the region where your Mimecast account is hosted as documented in the System Requirements section.\
**email\_address** is the email address of the user created in Step 1: Create a new user.

1. An example response to this command is:

|   | HTTP/1.1 200 OK                                                                                                                                                                                                                    |
| - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | **Content-Type**: application/json                                                                                                                                                                                                 |
|   | **Cache-control**: no-store                                                                                                                                                                                                        |
|   | **Pragma**: no-cache                                                                                                                                                                                                               |
|   | **Content-Length**: 375                                                                                                                                                                                                            |
|   | **Content-MD5**: 124911b164dbd3b9e823610a2eb4996a                                                                                                                                                                                  |
|   | **Date**: Mon, 25 Jul 2016 16:19:37 +0100                                                                                                                                                                                          |
|   | **Connection**: Keep-Alive                                                                                                                                                                                                         |
|   |                                                                                                                                                                                                                                    |
|   | {"meta":{"status":200},"data":\[{"accessKey":"LOWgx\_\_TRUNCATED\_\_Ect2nN","secretKey":"jD9DVicE2\_\_TRUNCATED\_\_EJdC4e/Q\u003d\u003d","duration":3153600000000,"bindingType":"one\_step","extendOnValidate":false}],"fail":\[]} |

1. Copy and paste the **accessKey** and **secretKey** values from the response to use in your application.
2. **IMPORTANT:** make sure to replace the **\u003d\u003d** at the end of the secret key with **==**\
   (\u003d is the uri encoding for the = symbol and is printed to the terminal, however the actual string should contain the = symbol when used)