User Email Address Operations using Active Directory Graph API

1
votes

I'm currently using the Microsoft.Azure.ActiveDirectory.GraphClient in a C# Cloud Service application that manages user provisioning and updates to users in Office 365 based on information stored in a database.

The issue I am facing is the setting of a user's mail address. On provisioning of a new user, setting the mail address property of the new user object causes an error to be thrown by the Graph Client. When provisioning a new user, the primary SMTP address is automatically set to the be the UPN for the user. The following code will successfully create a new user and set the primary SMTP address to be the same as the value set for the UserPrincipalName:

IUser newUser = new User();
newUser.DisplayName = "Firstname Surname";
newUser.UserPrincipalName = "someone@somewhere.com";
newUser.AccountEnabled = true;
newUser.MailNickname = "firstnamesurname";
newUser.ImmutableId = "0k3otwAAEkm8vGSKbJqRZg==";
newUser.PasswordProfile = new PasswordProfile
{
    Password = "somerandompassword",
    ForceChangePasswordNextLogin = true
};
newUser.UsageLocation = "GB";
_activeDirectoryClient.Users.AddUserAsync(newUser).Wait();

Fair enough - having UPN and primary email address mis-matches can cause AutoDiscover issues.

The problem I have is that the "mail" property of the user object also throws an error when set when updating a user.

The following code will successfully update a user:

User retrievedUser = new User();
List<IUser> retrievedUsers = null;
retrievedUsers = _activeDirectoryClient.Users
    .Where(searchUser => searchUser.ImmutableId.Equals(0k3otwAAEkm8vGSKbJqRZg==))
    .ExecuteAsync().Result.CurrentPage.ToList();
if (retrievedUsers != null && retrievedUsers.Count == 1)
{
    retrievedUser = (User)retrievedUsers.First();
        retrievedUser.UserPrincipalName = "someone1@somewhere.com";
        retrievedUser.UpdateAsync().Wait();
}

The above code will change the user's UPN, but not update the primary SMTP address as in the add a new user scenario. This I do not understand, as it can then cause AutoDiscover issues (as the UPN is different to the primary SMTP address) and negate any reason for not being able to set the mail address when creating a new user.

I cannot find any details on how to update a user's email address, or set an additional email address as the primary SMTP address. Scenarios for this requirement are such as when a user gets married and they want to have a new email address as their primary email address.

Does anyone have any info please on how to manage a user's primary SMTP address using Microsoft.Azure.ActiveDirectory.GraphClient? I can find information on setting additional email addresses, but not on how to change the primary SMTP address.

Grateful for any help please!

2
c#azureazure-ad-graph-api

2 Answers

0
votes

From testing this myself, an update to the userPrincipalName through the AzureAD Graph API automatically updates the following properties:

  • mail
  • userPrincipalName
  • proxyAddresses

With the proxyAddresses property being updated to include the new userPrincipalName as the new primary SMTP address, and the old primary address is preserved but no longer the primary address. This is also reflected in Exchange Online. The proxyAddress which is prefixed with SMTP: (uppercase) is the PrimarySmtpAddress.

As an edge case, this process does not happen if the previous primary address is not the same as the previous UPN. If the UPN and PrimarySmtpAddress do not match, then when the UPN is updated through the AzureAD Graph API then the new UPN will be added as a non-primary address, and the original primary address will remain the primary address.

As far as I know, this behavior is undocumented. However, something similar is documented here: https://support.microsoft.com/en-us/help/3190357/how-the-proxyaddresses-attribute-is-populated-in-azure-ad. It seems the priority of which property determines the PrimarySmtpAddress goes mail > UPN > mailNickName.

In general, I don't think it's a good idea to directly manipulate proxyAddresses because Exchange/AD already do a lot of this for you.

-1
votes

Following a random thought, I've figured out how to change the primary email address for a user in the above scenario. This is done by setting the primary email address in the proxy address list for the user, denoting the primary address with the prefix of "SMTP:" (note it has to be in CAPS):

retrievedUser.ProxyAddresses = new List<string>
{
    "SMTP: someone1@somewhere.com"
};

Hope this helps someone else!