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 |
|
userPrincipalName |
urn:scim:schemas:extension:custom:egnyte:1.0:User:idpUserId |
|
Always | Direct | Required for SSO |
|
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 | ||
|
False |
urn:scim:schemas:extension:custom:egnyte:1.0:User:validateEmail |
|
Always | Constant | Required if email change should be immediate |
| power | userType | Only during object creation | Constant | Optional. By default power. | |
| sso/ad/egnyte | urn:scim:schemas:extension:custom:egnyte:1.0:User:authType | Only during object creation | Constant | Optional. By default: SSO if SSO enabled on domain | |
| False | urn:scim:schemas:extension:custom:egnyte:1.0:User:sendInvite | Only during object creation | Constant | Optional. By default: False if authType SSO/AD | |
Additional notes:
- In order to edit attribute properties, click on the attribute line
- Red marked attributes need to be added manually before they can be used (see next paragraph)
- 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 custom or freed attributes, save your current changes and reload the page.
How to add custom attributes
Some mappings from the above table don't exist in Azure and have to be added manually.
In order to add them, please:
- Check “Show advanced options:
- Click “Edit attribute list for customappsso”.
- Scroll down and add all the attributes you need. All custom attributes are string type.
- Hit save, go back and reload the page.
- You should now be able to select the missing attributes as your target attribute.
Custom attributes you may want to use
The above scenario is most common, your requirements could be slightly different.
1. Authentication type:
If you want to set what the authentication type should be, follow these steps:
1.1. Click on the "Show advanced options" checkbox below the mapping list and then on the "Edit attribute list for customappsso."
1.2. At the end of the "Edit attribute list," add:
urn:scim:schemas:extension:custom:egnyte:1.0:User:authType
with type "string" and hit "Add attribute" (it can take some time to respond), then save and confirm changes.
1.3. Add constant mapping like on the below screenshot with one of these three values:
- sso - for Single-Sign-On authentication (Azure, Okta, ADFS, etc.)
- ad - for Active Directory authentication (AD)
- egnyte - standard Egnyte authentication
Disclaimer: Egnyte advises to have at least one admin account with authentication type "egnyte" in case of an AD/SSO provider's failure.
2. Service Accounts
If you want to provision service accounts from Azure, follow the steps from point 1 and add the custom attribute:
urn:scim:schemas:extension:custom:egnyte:1.0:User:serviceAccount
with type Boolean. Possible values here are true and false.
Adjust the mapping so that it corresponds to your requirements.
3. Two-factor authentication
If you want to enable two-factor authentication for accounts provisioned from Azure, follow the steps from point 1 and add the custom attribute:
urn:scim:schemas:extension:custom:egnyte:1.0:User:tfaEnabled
with type Boolean. Possible values here are true and false.
Disclaimer: If you set this mapping and you already use two-factor authentication for Microsoft accounts, your users will have to go through two-factor authentication twice, with Microsoft Authenticator and Authy.
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.
E.g., You want to create every user as a Standard user (power user is set by default). However, you want to be able to change the user type manually. Azure provisioning should not update this attribute after creation, as it would change the type back to standard.
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.
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.