Skip to main content

Data import

The Exchange Hybrid Connectivity relies on Microsoft Active Directory Connectivity and Microsoft Microsoft Entra ID Connectivity if using Exchange Hybrid for the correct operation. It is necessary to configure and import data from Active Directory and Microsoft Entra ID (for Exchange Hybrid Connectivity) before you can import data from Microsoft Exchange.

You likely have only one Microsoft Exchange system, but you can manage more Exchange systems if required. Two companies may merge without merging their Exchange systems:

  1. For each Exchange system, you must configure the following properties:

    • the connection details
    • the Active Directory (or Microsoft Entra ID) trust
    • the provisioning type
  2. Exchange Hybrid Connectivity integrates with Exchange using remote PowerShell. You must specify the URI to the PowerShell interface and the credentials associated with the system.

  3. After the initial load from Exchange, the new Exchange system is created in Omada Identity and is then ready for the remaining configuration.

  4. Configure the Active Directory (or Microsoft Entra ID) trust by specifying the system's domain (or domains) that the Exchange system integrates with.

  5. Configure the Exchange system to use OPS for provisioning of resource assignments.

General settings

SettingDescription
NameType a unique name for the system. Two systems cannot have the same name.
System IDType a unique System ID for the system. Two systems cannot have the same System ID. You cannot change this setting.
DescriptionType an optional description of the system.
StatusStatus of the system. Set the status to Removed to ensure the system is no longer included in warehouse imports, reconciliation, or provisioning. Setting a system as Removed will delete all objects referring to the system, including resources, manual and automated provisioning tasks, and assignment policies.
ContentThis option is disabled and can be selected only when onboarding the Exchange Hybrid Connector.
TrustsSelect one or more trusted systems to associate with the system.
Prevent self-serviceOptionally, decide if it will be possible or not to request the resource in a self-service requests in that system.
info

Trust is specifically designed for use between physical systems. It is not intended for use between logical and physical systems.

Connection details

SettingDescription
Server TypeSelect Local, if you are onboarding an on-premises Exchange organization. Select Hybrid, if you are onboarding a hybrid Exchange deployment. A hybrid Exchange deployment consist of an on-premises Exchange organization (Local) and Exchange Online (Cloud). When Local is selected, only the details for the on-premises Exchange will be visible.
Local: Connection URIThe URL for Exchange PowerShell, for example: https://[hostname]/powershell
Local: AuthenticationSelect the authentication method to use. Can be: Basic, Credssp, Default, Digest, Kerberos, Negotiate, Negotiate implicit credentials. Check in the Internet Information Services that the PowerShell folder under the Default Website is configured for the desired authentication type. You can configure the authentication methods for the /powershell URL the PowerShell cmdlet Set-PowerShellVirtualDirectory and not IIS. For more information refer to Microsoft documentation. You can find more information on various authentication types on Microsoft MSDN here.
Local: UsernameSpecify the username for the account that is used to read data from Exchange. If you leave this field blank, the username specified for importing is used.
Local: PasswordSpecify the password for the account used, if you have entered a username in the field above.
Local: Session optionsAdvanced options for the PowerShell session. For information about possible parameters and their functions, refer to the New-PSSessionOption article or the PSSessionOption Class article. - SkipCACheck -SkipCNCheck -SkipRevocationCheck
Local: Organizational unitOptional parameter. The parameter is not used for connecting, but for filtering the mailbox. It can be a simple name or a fully distinguished name like OU=MiniTest,DC=odwad,DC=test. For specifying multiple organizational units, use the | symbol to separate them.
Local: Import threadsSpecify the number of threads to use for import. Configure the number of simultaneous PowerShell sessions to use for retrieving the Send as and Full access information and speed up the run time for these two permissions. Use this setting for an asynchronous PowerShell to speed up the run time, wherever possible. Members of admin groups are fetched asynchronously. The default value is 6 (six) for Local and 1 (one) for Cloud.
Cloud: Connection URIThe URL for Exchange Online PowerShell. refer to Connect to Exchange Online PowerShell in order to find the right URL for your Exchange Online organization. Example: https://outlook.office365.com/powershell-liveid
Cloud: AuthenticationThe authentication method to use with the Exchange system. You can use the following authentication methods:

- Certificate thumbprint (on-premises only, not available in Omada Identity Cloud)
- Certificate with password

Cloud: OrganizationSpecify the organization that's used in certificate based authentication. Be sure to use an .onmicrosoft.com domain for the parameter value.
Cloud: Application IDSpecifies the application ID of the service principal that's used in certificate based authentication.
Cloud: Certificate (PEM format)Specify the certificate used for certificate based authentication. Value should be enclosed with -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
Cloud: Private key (PEM format)Specify the private key used for certificate based authentication. Value should be enclosed with -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----
Cloud: Session optionsAdvanced options for the PowerShell session. refer to New-PSSessionOption for the list of options. -SkipCACheck -SkipCNCheck -SkipRevocationCheck
Cloud: Import threadsSpecify the number of threads to use for import against Exchange Online. Check your tenant for max allowed sessions.
Test connectionEnable this setting to test the connection information that you have specified. If you want to use this functionality you must install Omada Provisioning Service and make sure it has the necessary permissions to communicate with the target system.

Queries and mappings

Out of the box, the Exchange Hybrid Connectivity provides the following mappings. The suggested list of destinations to have the History checkbox enabled:

  • PRIMARY_EMAIL
  • ADDITIONAL_EMAILS
  • HIDEINADDRESSLIST
  • ISSUEWARNINGQUOTA
  • PROHIBITSENDQUOTA
  • PROHIBITSENDRECEIVEQUOTA
  • WEBMAIL
  • MAILBOXLOCATION

Generic resources

Parameters

ParameterValue
SourceGeneric resources
Query scopeLocal
DistinctYes

Mappings

DestinationOperatorSource
Business keyExpressionstring.Format("<system>{0}</system><genericresource>{1}</genericresource>",BuiltIn.SystemShortName, BusinessKey)
Security resource business keyExpressionstring.Format("<system>{0}</system><genericresource>{1}</genericresource>",BuiltIn.SystemShortName, BusinessKey)
NameMapName
CategoryMapCategory
TypeMapType
Logical keyExpressionstring.Format("{0}_{1}", BuiltIn.SystemShortName, BusinessKey)

Role Groups

Parameters

ParameterValue
SourceAdministrative resources
Query scopeLocal and Cloud
DistinctNo
FilterType=="RoleGroups"

Mappings

DestinationOperatorSource
Business keyExpressionstring.Format("<system>{0}</system><resource>{1}</resource>",BuiltIn.SystemShortName, RoleGroupSamAccountName.ToLower() )
Security resource business keyExpressionstring.Format("<system>{0}</system><resource>{1}</resource>",BuiltIn.SystemShortName, RoleGroupSamAccountName.ToLower() )
NameMapRoleGroupName
CategoryConstantGroup
TypeConstantExchange Admin Role Group
Distinguished nameMapRoleDistingushedName
DescriptionMapRoleGroupDescription
ScopeMapScope
RoleGroup TypeMapRoleGroupType

Members group

Parameters

ParameterValue
SourceAdministrative resources
Query scopeLocal and Cloud
DistinctNo
FilterType=="Members" && RecipientType?.ToString().IndexOf("Group") !=-1

Mappings

DestinationOperatorSource
IndirectConstant0
Parent resource business keyExpressionstring.Format("<system>{0}</system><resource>{1}</resource>",BuiltIn.SystemShortName, RoleGroupSamAccountName.ToLower() )
Child resource - business keyLookupDistinguishedName=MemberDistinguishedName

Local user mailboxes

Parameters

ParameterValue
SourceMailboxes
Query scopeLocal
Mailbox subtypeUserMailbox,LinkedMailbox
DistinctNo
FilterType=="User mailbox"

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><genericresource>{1}</genericresource>",BuiltIn.SystemShortName,RecipientTypeDetails)
Account - CBKLookupPath=Identity
Business keyExpressionType=="User mailbox"?"<exchangeguid>"+ExchangeGuid+"</exchangeguid>":null
PRIMARY_EMAILMapPrimarySmtpAddress
ADDITIONAL_EMAILSMapEmailAddresses
HIDEINADDRESSLISTMapHiddenFromAddressListsEnabled
ISSUEWARNINGQUOTAMapIssueWarningQuota
PROHIBITSENDQUOTAMapProhibitSendQuota
PROHIBITSENDRECEIVEQUOTAMapProhibitSendReceiveQuota
WEBMAILMapOWAEnabled
MAILBOXLOCATIONMapMailboxLocation

Local shared mailboxes

Parameters

ParameterValue
SourceMailboxes
Query scopeLocal
Mailbox subtypeDiscoveryMailbox, EquipmentMailbox, GroupMailbox, LegacyMailbox, LinkedMailbox, LinkedRoomMailbox, RoomMailbox, SchedulingMailbox, SharedMailbox, TeamMailbox
DistinctNo
FilterIdentity != null && Type !="Full access" && Type !="Send as" && Type !="Send on behalf"

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><genericresource>{1}</genericresource>",BuiltIn.SystemShortName,RecipientTypeDetails)
Account - CBKLookupPath=Identity
Business keyExpressionType=="User mailbox"?"<exchangeguid>"+ExchangeGuid+"</exchangeguid>":null
PRIMARY_EMAILMapPrimarySmtpAddress
ADDITIONAL_EMAILSMapEmailAddresses
HIDEINADDRESSLISTMapHiddenFromAddressListsEnabled
ISSUEWARNINGQUOTAMapIssueWarningQuota
PROHIBITSENDQUOTAMapProhibitSendQuota
PROHIBITSENDRECEIVEQUOTAMapProhibitSendReceiveQuota
LINKEDMAILBOXDOMAINMapLinkedMasterAccount
WEBMAILMapOWAEnabled
MAILBOXLOCATIONMapMailboxLocation

Local mailbox access

Parameters

ParameterValue
SourceMailbox access
Query scopeLocal
Mailbox subtypeUserMailbox,EquipmentMailbox,RoomMailbox,SharedMailbox,LinkedMailbox
DistinctNo
FilterLinkedMasterAccount != null && LinkedMasterAccount != "NT AUTHORITY"

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><genericresource>{1}</genericresource>",BuiltIn.SystemShortName, Type == "Full access" ? "fullmailboxaccess": "sendasmailboxaccess")
Account - CBKLookupName=LinkedMasterAccount
Target - CBKExpressionstring.Format("{0}_<exchangeguid>{1}</exchangeguid>", BuiltIn.SourceSystemID, ExchangeGuid)
Business keyExpressionstring.Format("<account>{0}</account><resource>{1}</resource><target>{2}</target>", LinkedMasterAccount, Type, ExchangeGuid)
LinkedMasterAccountMapLinkedMasterAccount
AccessTypeMapType
MAILBOXREFExpressionstring.Format("{0}_<exchangeguid>{1}</exchangeguid>", BuiltIn.SourceSystemID, ExchangeGuid)

Local send on behalf (Resource assignment)

Parameters

ParameterValue
SourceMailboxes
Query scopeLocal
Mailbox subtypeUserMailbox,LinkedMailbox,DiscoveryMailbox,EquipmentMailbox,GroupMailbox,LegacyMailbox,LinkedRoomMailbox,RoomMailbox,SchedulingMailbox,SharedMailbox,TeamMailbox
DistinctNo
FilterType=="Send on behalf"

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><genericresource>sendonbehalfofmailboxaccess</genericresource>",BuiltIn.SystemShortName)
Account - CBKLookupPath=GrantSendOnBehalfTo
Target - CBKExpressionstring.Format("{0}_<exchangeguid>{1}</exchangeguid>", BuiltIn.SourceSystemID, ExchangeGuid)
Business keyExpressionstring.Format("<account>{0}</account><resource>{1}</resource><target>{2}</target>", GrantSendOnBehalfTo, Type, ExchangeGuid)
PRIMARY_EMAILMapPrimarySmtpAddress
IdentityMapIdentity
RecipientTypeDetailsMapRecipientTypeDetails
ExternalDirectoryObjectIDMapExternalDirectoryObjectID
GrantSendOnBehalfToMapGrantSendOnBehalfTo
MAILBOXREFExpressionstring.Format("{0}_<exchangeguid>{1}</exchangeguid>", BuiltIn.SourceSystemID, ExchangeGuid)

Local role assignments (Resource assignment)

Parameters

ParameterValue
SourceAdministrative resources
Query scopeLocal
DistinctNo
FilterType=="Members" && RecipientType?.ToString().IndexOf("Group") < 0

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><resource>{1}</resource>",BuiltIn.SystemShortName, RoleGroupSamAccountName.ToLower() )
Account - CBKLookupDistinguishedName=MemberDistinguishedName
DescriptionMapRecipientType

Cloud user mailboxes (Resource assignment)

Parameters

ParameterValue
SourceMailboxes
Query scopeCloud
Mailbox subtypeUserMailbox,LinkedMailbox
DistinctNo
FilterType=="User mailbox"

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><genericresource>{1}</genericresource>",BuiltIn.SystemShortName,RecipientTypeDetails)
Account - CBKLookupBusinessKey=ExternalDirectoryObjectID
Business keyExpressionType=="User mailbox"?"<exchangeguid>"+ExchangeGuid+"</exchangeguid>":null
PRIMARY_EMAILMapPrimarySmtpAddress
ADDITIONAL_EMAILSMapEmailAddresses
HIDEINADDRESSLISTMapHiddenFromAddressListsEnabled
ISSUEWARNINGQUOTAMapIssueWarningQuota
PROHIBITSENDQUOTAMapProhibitSendQuota
PROHIBITSENDRECEIVEQUOTAMapProhibitSendReceiveQuota
WEBMAILMapOWAEnabled
MAILBOXLOCATIONMapMailboxLocation

Cloud shared mailboxes (Resource assignment)

Parameters

ParameterValue
SourceMailboxes
Query scopeCloud
Mailbox subtypeDiscoveryMailbox, EquipmentMailbox, GroupMailbox, LegacyMailbox, LinkedMailbox, LinkedRoomMailbox, RoomMailbox, SchedulingMailbox, SharedMailbox, TeamMailbox
DistinctNo
FilterIdentity != null && Type !="Full access" && Type !="Send as" && Type !="Send on behalf"

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><genericresource>{1}</genericresource>",BuiltIn.SystemShortName,RecipientTypeDetails)
Account - CBKLookupBusinessKey=ExternalDirectoryObjectID
Business keyExpressionType=="User mailbox"?"<exchangeguid>"+ExchangeGuid+"</exchangeguid>":null
PRIMARY_EMAILMapPrimarySmtpAddress
ADDITIONAL_EMAILSMapEmailAddresses
HIDEINADDRESSLISTMapHiddenFromAddressListsEnabled
ISSUEWARNINGQUOTAMapIssueWarningQuota
PROHIBITSENDQUOTAMapProhibitSendQuota
PROHIBITSENDRECEIVEQUOTAMapProhibitSendReceiveQuota
LINKEDMAILBOXDOMAINMapLinkedMasterAccount
WEBMAILMapOWAEnabled
MAILBOXLOCATIONMapMailboxLocation

Cloud mailbox access (Resource assignment)

Parameters

ParameterValue
SourceMailbox access
Query scopeCloud
Mailbox subtypeUserMailbox,EquipmentMailbox,RoomMailbox,SharedMailbox,LinkedMailbox
DistinctNo
FilterLinkedMasterAccount != null && LinkedMasterAccount != "NT AUTHORITY"

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><genericresource>{1}</genericresource>",BuiltIn.SystemShortName, Type == "Full access" ? "fullmailboxaccess": "sendasmailboxaccess")
Account - CBKLookupName=LinkedMasterAccount
Target - CBKExpressionstring.Format("{0}_<exchangeguid>{1}</exchangeguid>", BuiltIn.SourceSystemID, ExchangeGuid)
Business keyExpressionstring.Format("<account>{0}</account><resource>{1}</resource><target>{2}</target>", LinkedMasterAccount, Type, ExchangeGuid)
LinkedMasterAccountMapLinkedMasterAccount
AccessTypeMapType
MAILBOXREFExpressionstring.Format("{0}_<exchangeguid>{1}</exchangeguid>", BuiltIn.SourceSystemID, ExchangeGuid)

Cloud send on behalf (Resource assignment)

Parameters

ParameterValue
SourceMailboxes
Query scopeCloud
Mailbox subtypeUserMailbox,LinkedMailbox,DiscoveryMailbox,EquipmentMailbox,GroupMailbox,LegacyMailbox,LinkedRoomMailbox,RoomMailbox,SchedulingMailbox,SharedMailbox,TeamMailbox
DistinctNo
FilterType=="Send on behalf"

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><genericresource>sendonbehalfofmailboxaccess</genericresource>",BuiltIn.SystemShortName)
Account - CBKLookupPath=GrantSendOnBehalfTo
Target - CBKExpressionstring.Format("{0}_<exchangeguid>{1}</exchangeguid>", BuiltIn.SourceSystemID, ExchangeGuid)
Business keyExpressionstring.Format("<account>{0}</account><resource>{1}</resource><target>{2}</target>", GrantSendOnBehalfTo, Type, ExchangeGuid)
PRIMARY_EMAILMapPrimarySmtpAddress
IdentityMapIdentity
RecipientTypeDetailsMapRecipientTypeDetails
ExternalDirectoryObjectIDMapExternalDirectoryObjectID
GrantSendOnBehalfToMapGrantSendOnBehalfTo
MAILBOXREFExpressionstring.Format("{0}_<exchangeguid>{1}</exchangeguid>", BuiltIn.SourceSystemID, ExchangeGuid)

Cloud role assignments (Resource assignment)

Parameters

ParameterValue
SourceAdministrative resources
Query scopeCloud
DistinctNo
FilterType=="Members" && RecipientType?.ToString().IndexOf("Group") < 0

Mappings

DestinationOperatorSource
Resource Business keyExpressionstring.Format("<system>{0}</system><resource>{1}</resource>",BuiltIn.SystemShortName, RoleGroupSamAccountName.ToLower() )
Account - CBKLookupUID=MemberName
DescriptionMapRecipientType

Distribution groups (Resource)

Microsoft Exchange Hybrid can also support local distribution groups. The default settings are configured for the cloud instance. To import local distribution groups, change the default queries.

note

By default, there is only one query for distribution groups. To onboard distribution groups and separately mail-enabled security groups, apply additional filtering. Use the DistributionGroupType attribute - provide the SecurityEnabled value to provision mail-enabled groups.

Parameters

ParameterValue
SourceDistribution groups
DistinctNo
FilterType==""DistributionGroups"

Mappings

DestinationOperatorSource
Business keyMapDistributionGroupGuid
Secret resource business keyMapDistributionGroupName
NameMapDistributionGroupName
CategoryConstantDistribution Group
TypeConstantExchange Distribution Group
Display nameMapDistributionGroupDisplayName
Account - CBKLookupBusinessKey=MemberExternalDirectoryObjectId

Default source fields

Add the DistributionGroup prefix to use any other field returned by the Get-DistributionGroup command. Example: To get the alias field, add the mapping for DistributionGroupAlias.

DistributionGroupName
DistributionGroupDisplayName
DistributionGroupDistinguishedName
DistributionGroupType
DistributionGroupPrimarySmtpAddress
DistributionGroupManagedBy
DistributionGroupHiddenFromAddressListsEnabled
DistributionGroupRequireSenderAuthenticationEnabled
Type

Distribution group members (Resource assignment)

Parameters

ParameterValue
SourceDistribution groups
DistinctNo
FilterType==""DistributionGroupMembers"

Mappings

DestinationOperatorSource
Resource business keyMapDistributionGroupGuid
Account - CBKLookupBusinessKey = MemberName

Default source fields

Add the Member prefix to use any other field returned by the Get-DistributionGroupMember command. Example: To get the ExchangeGuid field, add the mapping for MemberExchangeGuid.

DistributionGroupName
MemberDistinguishedName
MemberName
MemberDisplayName
MemberAlias
RecipientType
Type

Extension script

Utilizing the PowerShell extension script is supported for the Exchange collector.

To enable it specify the Script file name, containing available functions, in the Connection details section.

note

For local deployment provide the entire file path to the script file. For cloud deployment providing only the file name is sufficient.

You can implement extension script in two ways.

In the Queries and mappings section add a mapping with the Source parameter set to Script. Then configure the Function name parameter to indicate which function from the extension script file you want to utilize. Then specify the required mappings.

Parameters required for Script based query mapping

Alternatively, for the queries with source set to Mailboxes there is an additional parameter Extension attribute function name. The specified function is then performed after retrieving the mailboxes. This provides additional attributes, that are otherwise not available with the Get-Mailbox command.

This way PSObjects are returned with the ExchangeGuid, used for mapping results of the function mailbox return by query, and required attributes.

note

Each function utilizes the $serverType, with value either Local or Cloud, to differentiate the script behavior based on the mailbox location in the hybrid scenario.

Advanced queries and mappings configuration

If you require any custom mappings for your system implementation, this section describes the details of the fields available in the Queries and mappings task. This collector supports any number of queries and has the following query parameters which should be specified when creating or editing a query.

  • In the Distinct field, you can specify if the collector should remove possible duplicate rows.
  • In the Filter field under the Parameters section, you can provide a Dynamic Expresso expression that is used for filtering the data imported into Omada Identity. It returns a TRUE/FALSE result for each imported data row. If the expression returns "FALSE" for the given row that row is skipped during import.

The filter can be supplied with special functions #MinRow() or #MaxRow(). The #MinRow()/#MaxRow() are custom functions that can be combined with regular DynamicExpresso expressions thanks to the # prefix. For example, in line:

#MinRow(col1, col2)#col=="active"

the custom function is encapsulated with # at the start and optionally at the end if a regular filter is to be appended like in the example (col=="active").

The MinRow()/MaxRow() functions take two parameters. The intention is similar to a "Group by function" in SQL server that allows you to eliminate duplicates and to take the lowest or highest*[order by column]* for each [unique column] row, i.e., MinRow([unique column], [order by column]).

:::note[Example]:

MaxRow(UniqueKey, Version)

Input:

UniqueKeyVersion
11
12
22
21
31

Output:

UniqueKeyVersion
12
22
31
:::

Naming convention for mapping and expressions

The name used for mapping or expressions is converted into a name that is usable as a C# parameter.

Names can contain the characters _, a-z, A-Z, and 0-9, but the first character of the name cannot be a digit (0-9).

Furthermore, any forbidden characters will be stripped from the name under the conversion.

For example, $somekey1 becomes somekey1 and 1another_key becomes another_key.

Overriding onboarding configuration in import profile

To decrease the import time you can override the SendAs and FullAccess onboarding values in the import profile from the true, to the false value. Those exclude import of SendAs or FullAccess permissions respectively while executing Mailbox access query.

To do so, go to Import profile and add a separate line in the Overridden onboarding configuration field for each setting you want to override.

Import profile with the SendAs setting overridden.

Each entry for a configuration value should be in a separate line and have a following format.

Example

SettingName=NewValue

Advanced settings

When selecting the Use cache checkbox the executed PowerShell commands to get data from Exchange will be stored in local cache. When the same command is executed again for a different query, the result will be taken from cache resulting in faster execution.

Configure thresholds

The Configure thresholds function allows you to set the amount of changes that cannot be exceeded, relevant to the last import.

In the Configure import thresholds window, type a number (integer) in percentage for New objects, Modified objects, and Deleted objects to enable thresholds for the import of objects from this system.

The value for each operation is by default set to 0, which means that no threshold calculations take place for the operation(s) until you change the integer.

Account rules

Accounts reside in either Active Directory or Microsoft Entra ID, and the mailboxes refer to the accounts in these systems, so there is no configuration required for the Exchange Hybrid Collector in this regard. For the already onboarded Active Directory and Microsoft Entra ID systems, default account rules are provided, or you may have configured your own, but if you want to match the Shared, Room and Equipment Mailboxes additional configuration is required.