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. Azure AD is configured with Egnyte, and 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; just add a custom app as described below.
  4. You will need one non-gallery application for each Egnyte domain; however, you can use a single application for authentication for all the domains:
    Example:
    Name of application Provisioning for Single Sign-On for
    Egnyte US West acmeusw -
    Egnyte US East acmeuse -
    Egnyte EMEA and SSO acmeemea acmeusw, acmeuse, acmeemea

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 and 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 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 Okta identity provider, it can be used while generating a token for Azure.
  9. Test the connection, and hit Save button (you can also add email for notifications):
    mceclip3.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. You need to determine if the email addresses in Egnyte are consistent with Azure UPNs. If yes, these mappings will be sufficient:

mceclip4.png

These are bare minimal setup, and you can specify additional mappings to cover your needs.

4. If:

  • you are not sure if Azure UPNs are consistent with email addresses in Egnyte
  • you know that they aren't
  • you are going to use Single Sign-On

    please follow these steps:

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

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

4.3. Set mappings like on below screenshot:

mceclip3.png

4.4. These settings will make the following:

  • idpUsername in Egnyte will match UserPrincipialName with the highest precedence
  • In case of existing Egnyte users with inconsistent Azure UPN<->Egnyte username, mailNickname from Azure will be used to match usernames in Egnyte. mailNickname is part of the email address before @.
  • New users will be set to use SSO authentication!
  • Existing users will remain with their current authentication type.

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 "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 below screenshot with of these three values:

  • sso - for Single-Sign-On authentication (Azure, Okta, etc.)
  • ad - for Active Directory authentication (ADFS)
  • egnyte - standard Egnyte authentication

mceclip5.png

Disclaimer: Egnyte advises to have at least one admin account with authentication type "egnyte" in case of failure of AD/SSO provider.

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 take into account 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 while editing those mappings, you get to choose when those attributes should get updated. 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 Standard user (power user is set by default). You do, however, 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 that should be 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 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 some times.

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 around that using expressions or Azure AD custom attributes, but that requires a deep dive.
  3. Keep in mind that Azure AD, as well as on-prem AD, allows 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.