Exchange Agent 2023.03.27 - What's Changed

Exchange Agent 2023.03.27 Updates and Impacts

The RapidIdentity Exchange Agent has been updated to accommodate Microsoft's impending PowerShell deprecations.

Click here for more information regarding Microsoft's PowerShell deprecations.
Click here for instructions to update the RapidIdentity Exchange Agent to the 2023.03.27 version.

This update changes several Actions in the RapidIdentity Connect Office365 Adapter.

User Actions

saveOffice365MsolUser

• Creates or updates a user

• This action previously used Microsoft Online New-MsolUser to create users and that is replaced by Microsoft Graph New-MgUser

• This action previously used Microsoft Online Set-MsolUser to update users and that is replaced by Microsoft Graph Update-MgUser

• Creating a user now requires the following fields:

  • AccountEnabled
    • This is a new field in Microsoft Graph. The Exchange Agent will set the “AccountEnabled” field to “true” if not specified.
  • MailNickname
    • This is a new field in Microsoft Graph. The Exchange Agent will set the “MailNickname” field to the “DisplayName” value if it is not specified.
  • Password
    • If you create users without a password, you will need to update your Connect logic to supply a random password. Microsoft Online would automatically generate a random password when creating users without “Password” specified, but this is not the case with Microsoft Graph.
  • Special consideration should be taken when updating the “DisplayName” for a user (i.e. may also want to consider updating “MailNickname”).
    • See bullet point above regarding “MailNickname” not being specified on user create

Some User fields have changed names.

The Exchange Agent will automatically update the following fields when creating and updating a user:

• “FirstName” will be “GivenName”
• “LastName” is now “Surname”
• “Fax” is now “FaxNumber"
• “Office” is now “OfficeLocation”

License Changes

• The “AddLicenses” field will no longer accept an “AccountSkuId”. It will now accept either “SkuId” or “SkuPartNumber”.
• The “RemoveLicenses” field will no longer accept an “AccountSkuId”. It will now accept either “SkuId” or “SkuPartNumber”
• “SkuPartNumber” can be extracted from “AccountSkuId”.
  • Given “AccountSkuId=tp01n:DEVELOPERPACK_E5”, “SkuPartNumber=DEVELOPERPACK_E5” (i.e. everything after the colon in “AccountSkuId”).
• The “LicenseOptions” field will no longer accept an “AccountSkuId” in its JSON objects. Instead, it will accept “SkuId” or “SkuPartNumber”.
  • “LicenseOptions” are used for disabling specific plans within a license (e.g. “[{“SkuId”:”SkuId1”,”DisabledPlans”:[“YAMMER_ENTERPRISE”]}]”)

getOffice365MsolUsers

• Retrieves a list of users with optional max results and filter
• This action previously used Microsoft Online Get-MsolUser to retrieve users and that is replaced by Microsoft Graph Get-MgUser
• Filter changes
  • Careful consideration should be taken when updating Connect action sets utilizing the optional filter parameter. Microsoft provides documentation for using filters. An example filter object passed to getOffice365MsolUsers would be:

Old Way
-------
filter = createRecord(true)
setRecordFieldValue(filter, 'SearchString', 'Mi')

New Way
-------
filter = createRecord(true)
setRecordFieldValue(filter, 'Filter', 'startsWith(DisplayName, "Mi")')

getOffice365MsolUser

• Retrieves a specific user by unique identifier
• This action previously used Microsoft Online Get-MsolUser to retrieve users and that is replaced by Microsoft Graph Get-MgUser
• The “Identity”/”UserPrincipalName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when retrieving a specific user (i.e. A user can be found by providing either “UserPrincipalName” or “Id”).
• The “Identity” field will no longer be returned on the user objects. If the value is needed in Connect logic, utilize “UserPrincipalName” or “Id” instead.
• The “Id” field is now returned by user objects and should be used to reference users

deleteOffice365MsolUser

• Deletes a specific user by unique identifier
• This action previously used Microsoft Online Remove-MsolUser to delete users and that is replaced by Microsoft Graph Remove-MgUser
• The “Identity”/”UserPrincipalName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when deleting a specific user (i.e. A user can be deleted by providing either “UserPrincipalName” or “Id”).

Groups

saveOffice365MsolGroup

• Creates or updates a user
• This action previously used Microsoft Online New-MsolGroup to create groups and that is replaced by Microsoft Graph New-MgGroup
• This action previously used Microsoft Online Set-MsolGroup to update groups and that is replaced by Microsoft Graph Update-MgGroup
• Creating a group now requires the following fields:
  • DisplayName
    • It’s unlikely that groups were being created without the “DisplayName” field, but it was not required with Microsoft Online and is required by Microsoft Graph
  • MailNickname
    • This is a new field in Microsoft Graph. The Exchange Agent will set the “MailNickname” field to the “DisplayName” value if it is not specified.
  • MailEnabled
    • This is a new field in Microsoft Graph. The Exchange Agent will set the “MailEnabled” field to “false” if not specified.
  • SecurityEnabled
    • This is a new field in Microsoft Graph. The Exchange Agent will set the “MailEnabled” field to “true” if not specified.
  • Special consideration should be taken when updating the “DisplayName” for a group (i.e. may also want to consider updating “MailNickname”).
    • See bullet point above regarding “MailNickname” not being specified on group create

getOffice365MsolGroups

• Retrieves a list of groups with optional max results and filter
• This action previously used Microsoft Online Get-MsolGroup to retrieve groups and that is replaced by Microsoft Graph Get-MgGroup
• The “Identity” field will no longer be returned on the group objects. If the value is needed in Connect logic, utilize “DisplayName” or “Id” instead.
• The “Id” field is now returned by group objects and should be used to reference groups
• Filter changes
  • Careful consideration should be taken when updating Connect action sets utilizing the optional filter parameter. Microsoft provides documentation for using filters. An example filter object passed to getOffice365MsolGroups would be:

Old Way
-------
filter = createRecord(true)
setRecordFieldValue(filter, 'SearchString', 'Administrator')

New Way
-------
filter = createRecord(true)
setRecordFieldValue(filter, 'Filter', 'DisplayName eq Administrator')

getOffice365MsolGroup

• Retrieves a specific group by unique identifier
• This action previously used Microsoft Online Get-MsolGroup to retrieve groups and that is replaced by Microsoft Graph Get-MgGroup
• The “Identity”/”DisplayName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when retrieving a specific group (i.e. A group can be found by providing either “DisplayName” or “Id”).
• The “Identity” field will no longer be returned on the group objects. If the value is needed in Connect logic, utilize “DisplayName” or “Id” instead.
• The “Id” field is now returned by group objects and should be used to reference groups

deleteOffice365MsolGroup

• Deletes a specific group by unique identifier
• This action previously used Microsoft Online Remove-MsolGroup to delete groups and that is replaced by Microsoft Graph Remove-MgGroup
• The “Identity”/”DisplayName” field was used as the unique identifier for Microsoft Online, but the “Id” field is used by Microsoft Graph. The Exchange Agent will automatically handle this change when deleting a specific group (i.e. A group can be deleted by providing either “DisplayName” or “Id”).

addOffice365MsolGroupMember

• Adds a specific user as a member of a specific group
• This action previously used Microsoft Online Add-MsolGroupMember to add group members and that is replaced by Microsoft Graph New-MgGroupMember

deleteOffice365MsolGroupMember

• Removes a specific user as a member of a specific group
• This action previously used Microsoft Online Remove-MsolGroupMember to remove group members and that is replaced by Microsoft Graph Remove-MgGroupMemberByRef

Roles

getOffice365MsolRoles

• Retrieves a list of roles
• This action previously used Microsoft Online Get-MsolRole to retrieve roles and that is replaced by Microsoft Graph Get-MgDirectoryRole
• You may find that not all roles returned from Get-MsolRole are returned by Get-MgDirectoryRole. If this is the case, look at the “Import MsolRoles to MgDirectoryRoles” section below.

getOffice365MsolRole

• Retrieves a specific role by unique identifier
• This action previously used Microsoft Online Get-MsolRole to retrieve roles and that is replaced by Microsoft Graph Get-MgDirectoryRole
• You may find that not all roles returned from Get-MsolRole are returned by Get-MgDirectoryRole. If this is the case, look at the “Import MsolRoles to MgDirectoryRoles” section below.

addOffice365MsolRoleMember

• Adds a specific user as a member of a specific role
• This action previously used Microsoft Online Add-MsolRoleMember to add role members and that is replaced by Microsoft Graph New-MgDirectoryRoleMemberByRef

deleteOffice365MsolRoleMember

• Removes a specific user as a member of a specific role
• This action previously used Microsoft Online Remove-MsolRoleMember to remove role members and that is replaced by Microsoft Graph Remove-MgDirectoryRoleMemberByRef

Import MsolRoles to MgDirectoryRoles

This PowerShell script provides an example of how to import MSOL roles into Microsoft Graph. Run this in an Administrator PowerShell on the Windows machine where the Exchange Agent is installed with the appropriate credentials.

> $user = "admin_user@domain.onmicrosoft.com"
> $password = ConvertTo-SecureString 'password123' -AsPlainText -Force
> $basicCred = New-Object System.Management.Automation.PsCredential($user,$password)
> Connect-MsolService -Credential $basicCred
> $appId = "<azure_app_id>"
> $tenantId = "<azure_tenant_id>"
> $certThumbprint = "<cert_thumbprint>"
> $certPath = 'Cert:\LocalMachine\My\' + $certThumbprint
> $cert = Get-ChildItem -Path $certPath
> Connect-MgGraph -ClientId $appId -TenantId $tenantId -Certificate $cert
> Get-MsolRole | ForEach-Object {
    $template = (Get-MgDirectoryRoleTemplate -DirectoryRoleTemplateId $_.ObjectId)
    if ($template -ne $null) {
   	 $filter = "RoleTemplateId eq '" + $template.Id + "'"
   	 $role = Get-MgDirectoryRole -Filter $filter
   	 if ($role -eq $null) {
   		 New-MgDirectoryRole -RoleTemplateId $role.Id
   	 }
    }
}