Automating Microsoft Entra Employee Provisioning with Mimecast Email Gateway

Well-run technical organizations need to automate IAM access provisioning in order to quickly and securely onboard and off-board employees or contractors. This is often easier said than done.

System Components: Mimecast provides web email filtering gateways and services for many companies. Microsoft Entra (Azure AD) is Microsoft's online identity service for Azure and Office 365.

Automation Flow: A company wants to create new users in the Microsoft365 admin portal and fill out relevant AD metadata during the onboarding process. Afterwards, the user should be automatically added to Entra dynamic groups based on his or her department, job title, physical location, and other relevant attributes. User licenses should be assigned and baseline access should be granted automatically to the greatest extent possible. Technical Issue Description: The company utilizes Microsoft365 for its email system, but also has a Mimecast email gateway filter in place which filters incoming external messages before they can be delivered to employees. The Mimecast filter is connected to the directory and automatically syncs user lists 3x a day, in the US Central Timezone. The sync times are not configurable. The issue is that new users can be created at any time of day because the company has offices all over the world. Sometimes onboardings need to happen on the same day.

Unfortunately, the Mimecast gateway only syncs to the Entra AD 3x each day (8am-11am, 1pm-4pm, & 12am-3am) in US central time only, and this cannot be modified. This is suboptimal as it leaves new international users waiting many hours before a sync takes place. During this interval, internal company emails can be delivered but any external source emails are rejected.

To make matters worse, the automated IT provisioning process causes emails to be sent to the new user address within the first several minutes of account generation, all of which bounce back as undeliverable. The sending parties add the new user's email to their 'do not send' suppression lists, which prevents the IT department helpdesk from successfully resending the invites. The filter issue has caused so many problems that an iT staff member needs to manually login and run the filter sync as part of every onboarding process. The vendor also suggests manually provisioning the services which are leading to onboarding emails that are then suppressed, including Cisco Duo, Mimecast, Slack, Salesforce, and other relevant IT services. This could all be avoided if the Mimecast filter could sync more often... However, Mimecast does not allow it. They sync 3x a day in fixed windows and the company has no choice in the matter. If the IT department wants to run an out of bound sync to the directory, they need to manually login to the web filter admin console and click through several menus to run a manual directory sync. They also much do so before the automated provisioning sends the emails that get suppressed, which happens very quickly. Since this is difficult to do, they have given up on fully automating their onboarding process.

Solution: Mimecast has an API. We can call the API to run the execute sync operation defined here:https://integrations.mimecast.com/documentation/endpoint-reference/directory-sync/execute-sync/ We just need to figure out how to call the API endpoint we need programmatically whenever an onboarding event is taking place. To do this easily and keep it within the Microsoft Entra environment, I configured an Entra dynamic security group to use as a trigger for the automation. The dynamic group query ensures that all active users in the domain with an email license assigned will be added to the group.

Two additional pieces must be configured in Azure:

1. We need to create an Azure Logic App. The logic app will be triggered whenever a new user is added to the Azure AD group of licensed users. Whenever a new user is added to an Entra dynamic group, we can trigger an action from it. I configured the logic app to check the group membership for new employees every 5 minutes. You can use the drag-and-drop logic app designer with the prebuilt 'Office 365: when a group member is added or removed' module for this part of the process:

2. We also need to create an Azure Python Function which can actually call the Mimecast API and trigger a sync operation whenever it is invoked.

   Any time the Azure function is triggered, it will make a call to the Mimecast API endpoint for the company and trigger a full directory sync immediately. This functionality is equivalent to a human clicking the button in the admin portal manually and happens as soon as the Logic App runs.

Here is the code I used in the Azure Functions application for this solution; you will need to provide your API credentials for Mimecast in the # Setup required variables section.

import logging
import azure.functions as func
import base64
import hashlib
import hmac
import uuid
import datetime
import requests

def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request to execute Mimecast sync.')

    # Setup required variables
    base_url = "https://xx-api.mimecast.com"
    uri = "/api/directory/execute-sync"
    url = base_url + uri
    access_key = "YOUR ACCESS KEY"
    secret_key = "YOUR SECRET KEY"
    app_id = "YOUR APPLICATION ID"
    app_key = "YOUR APPLICATION KEY"

    # Generate request header values
    request_id = str(uuid.uuid4())
    hdr_date = datetime.datetime.utcnow().strftime("%a, %d %b %Y %H:%M:%S") + " UTC"

    # DataToSign is used in hmac_sha1
    dataToSign = ':'.join([hdr_date, request_id, uri, app_key])

    # Create the HMAC SHA1 of the Base64 decoded secret key for the Authorization header
    hmac_sha1 = hmac.new(base64.b64decode(secret_key), dataToSign.encode(), digestmod=hashlib.sha1).digest()

    # Use the HMAC SHA1 value to sign the hdrDate + ":" requestId + ":" + URI + ":" + appkey
    sig = base64.b64encode(hmac_sha1).rstrip()

    # Create request headers
    headers = {
        'Authorization': 'MC ' + access_key + ':' + sig.decode(),
        'x-mc-app-id': app_id,
        'x-mc-date': hdr_date,
        'x-mc-req-id': request_id,
        'Content-Type': 'application/json'
    }

    payload = {
        'data': [
            # Populate this with necessary data for the directory sync if required? Not clear if any payload needed: 
            # https://integrations.mimecast.com/documentation/endpoint-reference/directory-sync/execute-sync/
        ]
    }

    response = requests.post(url=url, headers=headers, json=payload)

    if response.status_code == 200:
        return func.HttpResponse("Directory sync executed successfully.", status_code=200)
    else:
        return func.HttpResponse(f"Failed to execute directory sync: {response.text}", status_code=response.status_code)

Results:

The company's baseline onboarding process now completes automatically within 30 minutes after a new user is setup in the Microsoft Admin portal. A variety of SCIM provisioning, base policy access, and dynamic group triggers like this have freed up the company's IT department to handle bigger and more complex problems without spinning their wheels with basic account provisioning tasks. Closing Notes: Panorbital's Microsoft-certified experts can help you build complex technical integrations that solve real business problems. We handle integration problems big and small. Give us a call (888 850 9585) or send an inquiry email ([e-mail]) if you're interested in working together.