Azure 101 (Engels)

This is an article regarding Azure AD and will cover different areas. The main purpose of this article is to understand the basics about how Azure AD works, as well as how to troubleshoot the integration.

The article will include information about the logic of Emply and will have information that should never be shared externally.

Appendix

• Azure AD basics
  • Tenant
  • Users
  • Groups
• Cloud/hybrid/On-prem
• Integrating Azure AD with Emply
  • Activating the integration
  • Configure the integration.
    • Step 1 add groups.
    • Step 2 Calendars.
    • Step 3. Activate two-way sync from Emply to AD.
• Troubleshooting the integration
  • Troubleshooting sync to Emply Issues
  • Troubleshooting sync from Emply to Azure

Azure AD basics

When looking at the Azure AD platform there are many options and pages, this can cause people to quicky get overwhelmed when first looking at it, but our integration only utilizes very few parts of the platform and those will be covered here.

Tenant

AD stands for active directory, the directory part is the whole Azure platform, in each directory we can have one or several tenants, the tenant is the place where the users and groups are stored.

Tenants does not syncronize data per default, but it is possible to set up cross-tenant options in Azure, but our system only looks at one tenant, so if a customer wants to have the integration on for several tenant, they will need to figure out how they want to syncronize data between tenants themselves.

A tenant consists of a lot of options and set up that can be done, we only use few of these options, primarily users and groups. A tenant will also have a primary domain, this is usually the domain the users will have as e-mail and username aswell.

Users

A user in a tenant does not have to always look the same, but some basic data always needs to be present on the users:

• UPN (User principal name): Always written as an e-mail and will also be the username in Emply.
• Mail Nickname: The e-mail adress for the user, will usually be the same as UPN, but it is possible to change in Azure.
• Display name: The displayed name of a user (does not have to be firstname/lastname).
• Password: Either auto generated or manually written.
• User status: Disable or Enable user.

The users also have properties, non of the properties are mandatory per default, so it can vary from tenant which properties are used.

We only use a few of the properties when getting users from Azure.

The last tab is assignments, this tab is used to assign the new user to groups or roles when it is created.

After a user has been created, it can be added to groups, it can also be given licenses to programs like Outlook or MS365, a user syncing to Emply will atleast need an Outlook license to use functionality like calendar sync.

After the user has been created we can look at which groups the user should be assigned to.

Groups

A group in Azure is one of the primary controllers of access, licences and data sent to third party software, like Emply. 

Several types of groups exsist, but the main ones we look at are 365 groups and security groups.

• 365 group: This group is used for 365 functionality and will have its own e-mail adress, adding members to this group would actions like giving access to a chanel in teams as an example.
• Security groups: This group is used primarily for access, by assigning roles to group members, or sending data to third parties.

When using the integration in Emply we would usually expect the customer to use a security group.

Adding members to a group can be automated in Azure, but most of the time it is done manually, this is an important note, as we only get members from groups added to Emply, so if a user is not beeing created, it is most likely not in the group at all.

Cloud/hybrid/On-prem

An Azure AD can come in 3 different types, these types beeing cloud, hybrid or on-prem.

• Cloud: Pure cloud based Azure AD, with all data located and handled on the cloud version of the platform, that can be accessed via a standard browser.
• Hybrid: A hybrid AD is a mix of Azure AD cloud and on-prem, a functionality called "Connect" is used to synchonize data between the two, but all data is still primarily handled in the on-prem AD.
• On-prem: On-prem AD is an on premises AD installed on a physical server that the customer maintans and owns themselves, this means that all data that should go from the AD and out, needs to be handled by the in-house administrator of the server.

Our integration only works 2-ways on cloud AD, on a hybrid AD we can still get the data 1-way from the cloud part of the AD, but we cannot write data as all data handling happens in the on-prem part of the AD.

Integrating Azure AD with Emply

When setting up the integration some requirements needs to be met.

• The customer only uses a cloud AD.
• Customers on hybrid AD's are made aware that the integration only works 1-way and data cannot be sent to their AD.
• The user activating the integration is a Global administrator of the tenant.

It is important that these requirements are met to prevent errors due to bad activation.

Activating the integration

Remember these steps have to be done by a global administrator of the AD, and only the global admintrator, activating the integration with a user with lesser permissions will cause issues.

When we want to activate the integration we are going to navigate to the integrations page in the UI, find the Azure AD integration and press activate, this will bring up a popup for activating the integration.

On the pop we press the "Connect" button, this will bring up a new pop-up with a Microsoft login screen.

All users that you have signed into a microsoft program with will show up here, make sure you pick the Global admin user of the tenant, or press "add account" to add it to the platform.

Once signed in a permissions box will appear where the admin will need to press Accept.

Once Accept is pressed a the system will load for a bit, while the enterprise app in Azure is beeing created, once done the activation pop-up will change to the config pop-up.

Configure the integration.

Once we have the configuration pop-up open, we can start configuring the integration, best practice while doing this is doing it step by step, untill every functionality that is wanted is active.

Step 1 add groups.

Press groups, this will show a dropdown of the groups on the tenant, choose which groups Emply should get users from.

When we add a group we will have to define some settings for the users:

• Default role: Role to be given for all users found in this group when beeing created in Emply, this option can also update current users, if "syncronize roles" is turned on.
• Default department: Department the user should be given when beeing created in Emply.
• Language: Language for user.
• Time zone: Time zone for user.
• Currency: Currency for user.

If several groups are added with different roles and departments, and a user is found in both groups, then the user will be given all the departments and all of the roles defined on each group.

Choose wether "synchonize roles" should be active or not, activating this setting will update all roles of current users that are present in the groups added to the integration.

Before making any other changes to the config, save this setup.

Step 2 Calendars.

Next step would be to choose weather to syncronize the Outlook calendar with Emply, enabling the Synchonizer calendar option wil enable the functionality, and then the ticker "always shared dates and titles with team members" will appear, enabling this option will turn the option on for all calendars currently in Emply, and have it on as standard for new calendars.

After saving the integration with the options enabled, the global admin should go their user settings in Emply, go to calendars and press the "+Outlook calendar" button, a new microsoft login should appear, where the Gloal admin should sign in with their AD user.

A new permissions request will appear, it is important that the admin checks the concent for organisation button.

Once done, it will take a bit to sync, after the sync has been completed the system will add all caledars for each users automatically, all calendars that user can edit will be added, but only the users main calendar will be activate.

Step 3. Activate two-way sync from Emply to AD.

After calendar sync is active and working we can look into the two-way sync, to start we should enable to functionality we want.

• Create: Will create users from Emply in Azure AD
• Update: Will update users in AD with changes from Emply.
• Delete: Will delete users in Azure AD when they are deleted in Emply.

When we enable create or update, we get a map fields button, this will allow us to map the elements from Emply to be connected to a specific element in Azure. 

No elements are mandatory, but will have to be mapped if the element should be part of the update functionality.

15 extension attributes can be mapped, these attributes does not send data to AD directly, but gives the customer an option create code themselves that adds these attributes to a specific property in Azure.

Once mapping is done then the integration should be saved again.

Troubleshooting the integration

Troubleshooting the integration can be a bit tricky, depending on the issue, sometimes its a simple case of doublicate profiles, but it might also be related to the customers own Azure AD setup.

Troubleshooting sync to Emply Issues

Usually sync to Emply issues is caused by one of two issues.

1.  The integration was not activated by a Global admin user, this will appear immidietly when the integration is activated the first time.
2. The platform has dublicated users.

This issue might not be immidietly be apparent as it requires some looking around in Hangfire.

To locate the correct job in hangfire, search for the platform in question under "tags" locate the latest "AzureRecurringSyncJob" and press it to see the details.

A job without issues will look something like this:

A job with a dublicate issue will look like this:

The marked area of the log shows what the value it is failing to add to a user is, in this case it is the ObjectId that should appear on the UUID on a user profile, this would indicate that the ID is already added to another user, as the id has to be unique.

We cannot filter by ID in the UI, so instead we can use the "Users" endpoint on api.emply.com to get a list of all users, we can then search the list for this ID to find which user it is connected to.

Once the dublicate and correct users have been located, adding the correct data to the correct user and deleteing the wrong user should fix the issue, but in some cases dev help is needed to fix some database values, and in those cases a ticket should be made for dev.

Troubleshooting sync from Emply to Azure

Troubleshooting sync from Emply to Azure is a bit more difficult, any error about this will appear in the integration log. 

Viewing the details of an error will show the error message provided by Azure

In some cases the error message will be clear, and in others it might be hard to figure out. 

Some quick things to always make sure is:

• Is the AD a pure cloud AD, if the answer is no then the customer should turn off this functionality.
• Is the user we are trying to update in one of the Azure AD groups added to Emply
• is the data on the user in Emply the same as the one in AD (is e-mail and UUID/objectid matching).
• Are there any dublicate users of the ones that are beeing updated.
• Is the user part of a special group in Azure that has extra security added.

If all the points above are fine, and if the message in integration log is not clear what the issue is, a meeting might be needed to check the setup of the AD with customer, if this does not yield results then we will need dev help for the issue.