HelloID-Conn-SA-Full-Exchange-Online-SharedMailboxCreate

ℹ️ Information
This repository contains the connector and configuration code only. The implementer is responsible for acquiring the connection details such as organization name, application ID, certificate, etc. You might need to coordinate with the client's application manager before implementing this connector.

Description

HelloID-Conn-SA-Full-Exchange-Online-SharedMailboxCreate is a delegated form designed for use with HelloID Service Automation (SA). It can be imported into HelloID and customized according to your requirements.

By using this delegated form, you can create a shared mailbox in Exchange Online and optionally assign permissions to users. The following options are available:

1. Enter the display name for the shared mailbox

   Display name is validated for uniqueness in Microsoft Entra ID

2. Enter the email address (prefix) and select a mail domain

   Email address is validated for uniqueness in Microsoft Entra ID

3. Optionally provide an alias (mailNickname) for the shared mailbox

   Alias is validated for uniqueness in Microsoft Entra ID

4. Optionally assign permissions to users

   Select permission type (Full Access, Send As, Send on Behalf) and choose users from a searchable grid

5. Create and configure the shared mailbox

   A shared mailbox is created using the provided display name and email address. The mailbox is then configured to receive copies of messages that are sent on behalf of it or as the mailbox itself. Selected permissions are granted to the specified users.

Getting started

Requirements

App Registration & Certificate Setup

Before implementing this connector, make sure to configure a Microsoft Entra ID App Registration. During the setup process, you'll create a new App Registration in the Entra portal, assign the necessary API permissions, and generate and assign a certificate.

Follow the official Microsoft documentation for creating an App Registration and setting up certificate-based authentication:

• App-only authentication with certificate (Exchange Online)

HelloID-specific configuration

Once you have completed the Microsoft setup and followed their best practices, configure the following HelloID-specific requirements.

• API Permissions (Application permissions):
  • User.Read.All - To validate email uniqueness by listing users via Graph API
  • Domain.Read.All - To retrieve verified domains for the mail domain dropdown
  • Exchange.ManageAsApp - To create and manage shared mailboxes
• Entra ID Role assignment:
  • Assign the Exchange Administrator role to the App Registration
• Certificate:
  • Upload the public key file (.cer) in Entra ID
  • Provide the certificate as a Base64 string in HelloID. For instructions on creating the certificate and obtaining the base64 string, refer to our forum post: Setting up a certificate for Microsoft Graph API in HelloID connectors

Connection settings

The following global variables must be configured in HelloID when importing and configuring the delegated form.

Setting	Description	Mandatory
EntraIdOrganization	The Entra organization name (domain)	Yes
EntraIdTenantId	The Entra tenant ID (GUID)	Yes
EntraIdAppId	The unique identifier (ID) of the App Registration in Microsoft Entra ID	Yes
EntraIdCertificateBase64String	The Base64-encoded string representation of the app certificate	Yes
EntraIdCertificatePassword	The password associated with the app certificate	Yes

Remarks

Display Name, Email Address & Alias Validation via Graph API

• Performance optimization: Instead of using the Exchange Online cmdlet Get-Mailbox (which can take 30+ seconds per query), the connector uses the Microsoft Graph API to validate display name, email address and alias uniqueness
• Validation scope: Checks for uniqueness across all types of objects in Entra ID (users, shared mailboxes, room mailboxes, equipment mailboxes, etc.)
• Graph API filters: Uses OData $filter queries on the following properties:
  • displayName - Display name
  • mailNickname - Mail nickname/alias
  • mail - Primary SMTP address
  • proxyAddresses - Proxy addresses (both smtp and SMTP variants)
• Three separate data sources:
  • EntraID-Check-DisplayName-Unique - Validates the display name uniqueness
  • EntraID-Check-EmailAddress-Unique - Validates the email prefix uniqueness
  • EntraID-Check-Alias-Unique - Validates the alias uniqueness (if an alias is provided)

Mailbox Creation and Configuration

Shared Mailbox Creation Process

When the form is submitted, the following process occurs in Exchange Online:

1. Create Shared Mailbox (New-Mailbox cmdlet)

   • Mailbox type: Shared mailbox
   • Display Name: Set to the value entered in the form
   • Mailbox Name: Set to the value entered in the form
   • Primary SMTP Address: Constructed from email prefix + selected mail domain (e.g., prefix@domain.com)
   • Alias: If provided, uses the specified alias; otherwise defaults to the email prefix
   • Recipient Type: SharedMailbox

2. Wait for Exchange Processing

   • A 10-second delay is implemented to allow Exchange Online to finalize the mailbox creation
   • This ensures the mailbox object is fully available for subsequent configuration

3. Configure Mailbox Settings (Set-Mailbox cmdlet)

   • The following properties are explicitly enabled:
     • MessageCopyForSendOnBehalfEnabled: Set to $true
       • Enables the mailbox to receive a copy of messages when someone sends on behalf of the mailbox
     • MessageCopyForSentAsEnabled: Set to $true
       • Enables the mailbox to receive a copy of messages when someone sends as the mailbox
   • These settings ensure the shared mailbox owner receives copies of all messages sent using the mailbox's identity or delegated permissions

Permission Assignment (Optional)

If permissions are selected in the form, the following permissions can be granted to users immediately after mailbox creation:

1. Full Access (Add-MailboxPermission cmdlet)

   • Grants the user full access to the shared mailbox
   • Allows the user to open and read all items in the mailbox
   • AutoMapping setting determines whether the mailbox appears automatically in the user's Outlook
   • Optionally includes Send As permission (configurable via checkbox)

2. Send As (Add-RecipientPermission cmdlet)

   • Grants the user the ability to send messages as the shared mailbox
   • Messages appear to come directly from the shared mailbox address
   • Recipients cannot tell that the message was sent by someone else

3. Send on Behalf (Set-Mailbox cmdlet with GrantSendOnBehalfTo parameter)

   • Grants the user the ability to send messages on behalf of the shared mailbox
   • Messages show "Sent by [User] on behalf of [Shared Mailbox]"
   • Recipients can see who actually sent the message

Permission Assignment Features:

• Multiple users can be selected from a searchable grid populated with all Entra ID users (excluding guests)
• Permissions are assigned during the form submission process, immediately after mailbox creation
• Each permission type can be assigned independently or in combination
• Full Access can optionally include Send As permission via a checkbox option
• All permission assignments generate individual audit log entries for tracking

Development resources

API endpoints

The following Microsoft Graph API endpoints are used by the connector:

Endpoint	Description
/v1.0/domains	Retrieve all verified domains with Email support for the mail domain dropdown
/v1.0/users	Search and retrieve users to validate display name, email address and alias uniqueness, and to populate the user selection grid for permission assignment

PowerShell Cmdlets

The following PowerShell cmdlets are used by the connector:

Cmdlet	Description
Connect-ExchangeOnline	Establish session to Exchange Online using certificate-based app-only authentication
New-Mailbox	Create the shared mailbox with specified properties
Set-Mailbox	Configure mailbox delegation settings after creation and grant Send on Behalf permissions
Add-MailboxPermission	Grant Full Access permissions to users
Add-RecipientPermission	Grant Send As permissions to users
Disconnect-ExchangeOnline	Close the Exchange Online session

Documentation

For more information on the APIs and PowerShell cmdlets used in this connector, please refer to:

Microsoft Graph API:

• Authentication with certificate
• List domains
• List users - Advanced query capabilities
• User resource reference

Exchange Online PowerShell:

• Exchange Online PowerShell overview
• Connect-ExchangeOnline
• New-Mailbox
• Set-Mailbox
• Add-MailboxPermission
• Add-RecipientPermission
• Disconnect-ExchangeOnline

Getting help

💡 Tip:
For more information on Delegated Forms, please refer to our documentation pages.

HelloID docs

The official HelloID documentation can be found at: https://docs.helloid.com/