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

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

Copy and paste the base URL 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. For a description of Mimecast SIEM logs, see Understanding SIEM Logs.

Add a custom API application for integration with BluSapphire

You must add an API application 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: [e-mail]

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

You must create a user profile with the correct permissions to generate API keys for Mimecast collector authentication.

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:

$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"

$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)