This guide will walk you through how to set up users and groups provisioning from Azure AD. To set up Azure Single Sign On (SSO), please refer to this article.
Prerequisites
- Microsoft Azure plan allows for a custom, non-gallery application (if groups are to be provisioned, the plan should allow for this as well)
- If you have a local Active Directory present, it should be synced with Azure. Please refer to this Microsoft article.
- Do not add the Egnyte App from the Azure App Gallery; add a custom app described below.
- Egnyte recommends setting up a separate application for every Egnyte domain you have:
Example:
Although it is possible to set up SSO within one application, we do not recommend it.Name of application Provisioning for Single Sign-On for Egnyte US West acmeusw acmeusw Egnyte US East acmeuse acmeuse Egnyte EMEA acmeemea acmeemea
Step-by-step guide
Creating Enterprise applications for provisioning
- Log in to Azure Portal.
- Go to Enterprise Applications in the Azure AD section.
- Hit the "+ New application" button and then "+ Create your own application." This can require a specific plan that might include additional costs.
- Choose the name of App so it can be easily identified. Select:
"Integrate any other application you don't find in the gallery." - Click on the newly created app, select "Provisioning Section," and click the "Get started" button.
- Set provisioning mode to automatic.
- Provide your tenant URL by changing <domain> to your Egnyte domain:
https://<domain>.egnyte.com/pubapi/scim/v2/azure
Disclaimer: This URL can not be used with other identity providers! - Go to https://eg-okta-scim.appspot.com/ to generate a Secret Token for your domain. You will have to log in with your domain admin credentials (a service account is recommended).
Disclaimer: even though this portal was initially created for the Okta identity provider, it can be used while generating a token for Azure. - Test the connection, and hit the Save button (you can also add email for notifications):
Mapping Attributes
Here we set up mappings between Azure AD object attributes and Egnyte object attributes. Please note that you will be able to edit the mappings only when you have successfully tested the connection and saved the basic configuration.
Group mappings
Go to your application in Azure -> Provisioning -> Edit provisioning. Click on "Mappings" and then "Provision Azure Active Directory Groups."
Set mappings in the following way:
Disclaimer: Group provisioning may require a different Azure plan.
User mappings
Go to your application in Azure -> Provisioning -> Edit provisioning. Click on "Mappings" and then "Provision Azure Active Directory Users."
The following table shows an example of mappings that covers most scenarios:
| Attribute properties | |||||
|---|---|---|---|---|---|
|
Azure Active Directory Attribute |
customappsso Attribute |
Matching precedence |
Apply this mapping | Mapping type | Notes |
|
Word([userPrincipalName], 1, "@") |
userName |
1 |
Only during object creation | Expression | Usernames can only be updated manually |
|
objectId |
externalId |
2 |
Always | Direct | Mandatory |
|
Not([IsSoftDeleted]) |
active |
|
Always | Expression | Mandatory |
|
givenName |
name.givenName |
|
Always | Direct | Mandatory |
|
surname |
name.familyName |
|
Always | Direct | Mandatory |
|
IIF(IsPresent([mail]),[mail],[userPrincipalName]) |
emails.value |
|
Always | Expression | Both are required for email updates. (due to Azure SCIM limitations) |
|
IIF(IsPresent([mail]),[mail],[userPrincipalName]) |
emails[type eq "work"].value | Only during object creation | Expression | ||
| power | userType | Only during object creation | Constant | Optional. By default power. | |
Additional notes:
- In order to edit attribute properties, click on the attribute line
- Some attributes can be unavailable since they are already used with default mapping. Remove default mappings in order to free them up.
- If you don't see freed attributes, save your current changes and reload the page.
Additional comments to mappings
There are many ways you can customize those mappings (depending on your setup). Azure allows for a:
- direct mapping (Azure attribute is sent to Egnyte as is)
- constant mapping (there is an arbitrary constant value set, independent from Azure AD attributes)
- expression mapping. The last one allows for the most flexibility. You can find more about expressions in this Microsoft article.
Keep in mind that you get to choose when those attributes should get updated while editing those mappings. Always, Upon Object Creation, or Only when there are multiple values for one attribute. This is important for attributes that should not change after being created once.
Provisioning
1. Adding users and groups to the scope
Once the mapping is configured and saved, you need to add users and groups to the scope by going to the application in Azure and then to "Users and groups." Keep in mind that only explicitly added groups will be created in Egnyte. Nested groups will be ignored. Users in nested groups will also be ignored.
2. Narrowing the scope
The scope can be narrowed down. E.g., You have groups created in Egnyte but want to exclude certain users like admins from being provisioned.
To narrow down the scope, follow these steps:
- Go back to user attribute mappings.
- Open "Source Object Scope."
- Here you can create filters based on attributes to include/exclude certain users or user sets. E.g., You do not want to manage the primary admin user via SCIM, but it should stay in the provisioned group in Azure. Create a filter like this: userPrincipalName NOT EQUALS <UPN for the admin account>
3. Test/troubleshoot provisioning
Go to your application -> Provisioning -> Provisioning on demand. Try to provision some users. Check in Egnyte if every attribute maps correctly. Unfortunately, provisioning on demand is not available for groups.
4. Enabling provisioning
If tests passed, you can enable provisioning by going to your application -> Provisioning -> Edit provisioning and enable provisioning:
Provisioning is an automated process from Azure's side, which runs every 40 minutes, and there is no control over this period. Depending on the number of users, the initial sync should take only a few minutes, but it can take several hours sometimes.
5. Deactivating and deleting users
Users will be deactivated in Egnyte when:
- They are removed from the application scope
- They are soft deleted in Azure AD
Users will be deleted in Egnyte when:
- They are permanently deleted in Azure AD (by default 30 days after soft delete)
The change will take effect after the first successful provision. We can manually trigger the change by running provisioning on-demand.
6. Deleting groups and its impact on users
Groups will be deleted in Egnyte when:
- They are removed from the application scope
- They are deleted in Azure AD
What will have to users when a group is deleted?
- Nothing (If the user is part of another group OR has been separately provisioned individually)
- They will be deactivated (if the only provisioning source was the deleted group) - but they won't be deleted.
LIMITATIONS and CAVEATS
- There are user account changes that should be performed manually, though. The user type is one of them. However, using dynamic groups in Azure or applying a custom attribute to users may allow for easy user type control.
- Keep in mind that groups do not get owners. There are ways to use expressions or Azure AD custom attributes, but that requires a deep dive.
- Keep in mind that Azure AD and on-prem AD allow you to use custom attributes. Those can be mapped to Egnyte just as easily. E.g., user type cannot be obtained by group affiliation but can be added as a custom attribute via PowerShell script. Then, such an attribute can be mapped to Egnyte as userType, allowing you to control user type from within AD and without the need to log into Egnyte at all.
- Service accounts are recommended for the token generation, as deactivating or deleting the account may render the SCIM integration incapacitated.
- The sync is one way. No changes to Egnyte will be reflected in Azure.