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 it can be easily identified. Select: 
    "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 (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. 
  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 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."

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

The following table shows an example of mappings which covers most scenarios:

  Attribute properties

Azure Active Directory Attribute

customappsso Attribute

Matching precedence

Apply this mapping Mapping type Notes

objectId

externalId

1

Always Direct Mandatory

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

userName

2

Only during object creation Expression Usernames can only be updated manually

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

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

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

  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/troubleshoot 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'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

  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.