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

  1. Microsoft Azure  plan allows for a custom, non-gallery application (if groups are to be provisioned, the plan should allow for this as well)
  2. If you have a local Active Directory present, it should be synced with Azure. Please refer to this Microsoft article
  3. Do not add the Egnyte App from the Azure App Gallery; add a custom app described below.
  4. Egnyte recommends setting up a separate application for every Egnyte domain you have:
    Example:
    Name of application Provisioning for Single Sign-On for
    Egnyte US West acmeusw acmeusw
    Egnyte US East acmeuse acmeuse
    Egnyte EMEA  acmeemea acmeemea
    Although it is possible to set up SSO within one application, we do not recommend it.

Step-by-step guide

Creating Enterprise application for provisioning

  1. Log in to Azure Portal.
  2. Go to Enterprise Applications in the Azure AD section.

    mceclip0.png

  3. Hit the "+ New application" button and then "+ Create your own application." This can require a specific plan that might include additional costs.

    mceclip2.png
  4. Choose the name of App so you can easily identify and choose the option.
    "Integrate any other application you don't find in the gallery."
  5. Click on the newly created app, select "Provisioning Section," and click the "Get started" button.
  6. Set provisioning mode to automatic.
  7. 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!
  8. 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.
    Disclaimer: even though this portal was initially created for the Okta identity provider, it can be used while generating a token for Azure.
  9. Test the connection, and hit the Save button (you can also add email for notifications):
    mceclip0.png

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 mapping 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."

To make mapping working with Egnyte, you need to delete "objectId" and save.

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."

1. Delete all unnecessary mappings, leave only these:

mceclip0.png

2. Save the mapping (this is a crucial step to free up some mappings)

3. Set the mappings as follows. Use apply always for all of them. For userName, use this expression:

Word([userPrincipalName], 1, "@")

mceclip1.png

4. We need to set up two different mappings for emails:

4.1. In the above mapping for email address provide these changes:

mceclip0.png

This mapping will be used during user creation in Egnyte.

4.2. Click on the "Show advanced options" checkbox below the mapping list and then on the "Edit attribute list for customappsso."

4.3. At the end of the “Edit attribute list,” add:

emails.value

mceclip0.png
With type “string” and hit “Add attribute” (it can take 10 seconds to respond), then Save and confirm changes. Exit and enter the user mapping section again to load the newly added attribute.

4.4. Set mapping for newly added attribute:

mceclip3.png

If you do not see the correct target value, reload the Azure page. This mapping will update an email if it changes in Azure.

5. If you do not want users to validate an email address every time it changes in Azure, you need to add another custom mapping.

5.1. Click again on the "Show advanced options" checkbox below the mapping list and then on the "Edit attribute list for customappsso."

5.2. At the end of the "Edit attribute list," add:

urn:scim:schemas:extension:custom:egnyte:1.0:User:validateEmail

mceclip8.png

with type “string” and hit “Add attribute” (it can take 10 seconds to respond), then Save and confirm changes. Exit and enter the user mapping section again to load the newly added attribute.

5.3.Set mapping for newly added attribute:

mceclip5.png

6. If you are going to use Single Sign-On and you need to add a custom attribute:

6.1. Click again on the "Show advanced options" checkbox below the mapping list and then on the "Edit attribute list for customappsso."

6.2. At the end of the "Edit attribute list," add:

urn:scim:schemas:extension:custom:egnyte:1.0:User:idpUserId

mceclip1.png

with type "string" and hit "Add attribute" (it can take 10 seconds to respond), then Save and confirm changes. Exit and enter the user mapping section again to load the newly added attribute.

6.3. Set mapping for newly added attribute:

mceclip6.png

7. In the end, mappings should look like this (with Single Sign-On enabled):

mceclip2.png

Setting idpUsername in Egnyte will automatically change the user's authentication to SSO!

8. Limitations:

  • There is no possibility to automatically update the username when it is changed in Azure.

Additional attributes you may want to use

These scenarios are most common, and your needs could be slightly different.

1. Authentication type:

If you want to set what should be authentication type for provisioned users, 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 of "string" and hit "Add attribute" (it can take 10 seconds 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

mceclip5.png

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.

And sets conditions that will correspond to your needs.

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: Please consider that if you already use two-factor authentication with your SSO provider, your users will have to go through two-factor authentication twice.

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 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 would 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:

  1. Go back to user attribute mappings.
  2. Open "Source Object Scope."
  3. 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 provisioning

Go to your application -> Provisioning -> Provisioning on demand. Try to provision some users and groups. Check in Egnyte if every attribute maps correctly.

4. Enabling provisioning

If tests passed, you can enable provisioning by going to your application -> Provisioning -> Edit provisioning and enable provisioning:

mceclip6.png

Provisioning is an automated process from the Azure 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.

LIMITATIONS and CAVEATS

  1. 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.
  2. 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.
  3. 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.
  4. Service accounts are recommended for the token generation, as deactivating or deleting the account may render the SCIM integration incapacitated.
  5. The sync is one way. No changes to Egnyte will be reflected in Azure.