Lesson 4: Integration with Active Directory

Part 2: Configuring User Authentication with

The integration of Acumatica ERP with Microsoft Active Directory (AD) provides centralized management of users and access. After integration, your domain users can use their domain user names and passwords to sign in to Acumatica ERP. You can set up integration with AD if Acumatica ERP is installed in your organization’s intranet. If your Acumatica ERP instance is deployed in the external network, you must use Active Directory Federation Services to provide access to the system for your domain users.

You can create, delete, and manage user accounts by using Active Directory. Users’ access rights to Acumatica ERP are determined based on the mapping rules between AD groups and Acumatica ERP roles. In this lesson, you will learn how to configure and manage Acumatica ERP integration with Active Directory.

Lesson Objectives You will learn how to do the following (you do not need to perform the steps to pass the training):

Enable Active Directory Integration
Map Active Directory groups to roles in Acumatica ERP instance
Set up role assignment for domain users | About Integration with Active Directory | 51

About Integration with Active Directory

You can integrate Acumatica ERP with Microsoft Active Directory (AD) to manage users and access in one place. You can create, delete, and manage user accounts by using AD. During integration you map AD groups with user roles in Acumatica ERP to determine users’ access rights. Important! Enabling integration with AD does not affect the standard authorization and authentication mechanism of Acumatica ERP. With the AD integration enabled, you still can create regular (non-AD) users in Acumatica ERP.

Configuration Steps To integrate an instance of Acumatica ERP with AD, you do the following:

Enable integration with Active Directory by modifying the web.config file of the application instance.
Map the user roles configured in Acumatica ERP to the groups configured in the Active Directory domain by using the User Roles (SM201005) form in Acumatica ERP.
Optional: If you need to override roles assigned to AD users, manually add the AD user accounts to the system (if necessary) and specify the roles for the accounts.
User Accounts of Domain Users in Acumatica ERP After you have enabled integration with the identity management system, user accounts for domain users are created automatically when the users sign in to your Acumatica ERP instance for the first time. The accounts of domain users in Acumatica ERP are based on their accounts in the domain. The password of a domain user in Acumatica ERP is the same as the domain account password. The email address and the first and last name of the user are populated from the domain account as well. However, the login, password, email address, and first and last name are managed through the domain and cannot be changed in Acumatica ERP. Important! You cannot restore the passwords of domain users by using Acumatica ERP tools. You should restore users’ domain credentials by using tools of Active Directory (AD). If the number of users or groups in AD is greater than or equal to 1000, information about users and groups from AD is automatically cached by Acumatica ERP to speed authentication of users. When you make any changes in AD, you can manually synchronize the cached lists of users and groups with AD in Acumatica ERP. If the number of users and groups in AD is less than 1000, Acumatica ERP retrieves the lists of users and groups directly from AD.
Domain User Authentication Generally, to sign in to Acumatica ERP, AD users type their domain credentials without specifying the domain name. But some employees may have both a local user account and a domain user account with the same user name. In this case, Acumatica ERP will authenticate the users based on the password they specify (assuming that the local and domain passwords differ). If both the user names and the passwords are the same for a local user account and a domain user account, on the Welcome screen, the user can select the account to sign in with as follows:

To sign in with a local account, the user enters the user name of the local account (as usual).

To sign in with a domain account, the user enters the login in the <Domain_Name><User_Name> format, where <Domain_Name> is the NetBIOS domain name of the integrated domain and <User_Name> is the user account name in the integrated domain.

     If there is a local account with the name which includes a domain name and a user name from this
     domain, for example, Terra\User1, a domain user with the name User1 from domain Terra will be
     mapped to this local account and will inherit all permissions of this account. In this case passwords of

| About Integration with Active Directory | 52

   a local user and a domain user may differ but they both will access the same user account. To prevent
   confusion, we recommend that you disable or delete the local accounts of employees who do not perform
   any administration or configuration tasks in Acumatica ERP.

Domain User Authorization When a domain user tries to access Acumatica ERP, user authorization occurs as follows:

The application instance sends an authentication request to the AD server to validate the user’s credentials.
When validation has completed successfully, the AD server sends Acumatica ERP the list of AD groups to which the user is assigned.
Acumatica ERP compares the list of AD groups with the internal Acumatica ERP roles, based on the mapping rules defined on the User Roles (SM201005) form.
The system finds any Acumatica ERP roles that are associated with AD groups to which the domain user account is assigned. If Acumatica ERP finds at least one role, the user is authenticated to sign in to the Acumatica ERP instance. The user access rights within the Acumatica ERP application instance are based on the internal list of roles.

Access Rights of Domain Users Domain users inherit access rights from the AD groups that you mapped to Acumatica ERP user roles. In addition, you can assign specific user roles to each domain user if the access rights for this user should differ from the AD group rights. New domain users automatically get the rights to sign in to Acumatica ERP when they join a domain. The membership of these users in Acumatica ERP roles is then automatically updated to comply with the membership of the users in the domain groups. | Step 4.1: Enabling Active Directory Integration | 53

Step 4.1: Enabling Active Directory Integration In this step you will enable integration in Acumatica ERP to be able to integrate your Acumatica ERP instance with Active Directory (AD). After you save changes to the web.config file, the website is automatically restarted. Make sure that all users are warned about the restart so that they can save their documents in advance.

To enable Active Directory integration, do the following:

Create an AD user account that has Read permissions throughout the entire AD forest. This user account must be included in the Domain Users group or have at least Read permissions to the following properties defined in the AD schema: objectSid, distinguishedName, sAMAccountName, displayName, description, lastLogon, pwdLastSet, primaryGroupID, and memberOf.
Modify the web.config file as follows:

Open the web.config file, which is located in the folder that contains the application instance website. After you save changes to the web.config file, the website is automatically restarted. Make sure that all users are warned about the restart so that they can save their documents in advance.

In the file, find the activeDirectory section within the system.web section and edit it similarly to the example shown below.

           <activeDirectory
                          enabled="true"
                          path="Domain_Path"
                          dc="Domain_Name"
                          user="User_Name"
                          password="User_Password" />

          In the code shown above:

Domain_Path is the DNS name or the IP address of the domain controller (DC).
Domain_Name is the domain name, such as terra, terra.com, or sing.terra.com. This setting affects the visibility of the data of Acumatica ERP to the domain users. Preferably, you should use the highest-level domain of the domain name. For example, in the sing.terra.com domain name, the highest level domain is sing, and you would have to specify dc=“sing“. For the terra.net domain, the highest level domain is terra and you would have to specify dc=“terra“.
User_Name is the name of the user account you created in Step 1. Depending on the AD settings, you should use one of the following formats: User_Name, User_Name@Domain_Name, or Domain_Name\User_Name.
User_Password is the AD password of the user account you created in the first instruction.
Save the web.config file. The website restarts automatically. Now you can proceed to mapping AD groups to Acumatica ERP roles. | Step 4.2: Mapping Active Directory Groups to Roles in Acumatica ERP | 54

Step 4.2: Mapping Active Directory Groups to Roles in

Acumatica ERP

In this step, you will map AD groups to Acumatica ERP roles. Before you start configuring your system, make sure that all the domain users have email addresses configured in AD. Enabling AD integration does not affect the standard authorization and authentication capabilities of Acumatica ERP. With AD integration enabled, you can still create internal users in Acumatica ERP.

To map Active Directory groups to Acumatica ERP roles, do the following:

Sign in to your Acumatica ERP instance.
Navigate to the User Roles form (SM201005; Configuration > User Security > Manage).
In the Summary area, in the Role Name box, select the role you want to associate with an Active Directory group (or with multiple groups).
On the Active Directory tab, click Add Row. The Active Directory tab appears on this form if the integration of Acumatica ERP with AD has been enabled in the web.config file.
In the Group column on the new row, select the AD group that you want to associate with the role.
On the form toolbar, click Save. You have to repeat the above instructions for every role that should be mapped to AD groups. If you need, you can remove mapping on the same User Roles form (SM201005). After you have mapped AD groups with user roles in Acumatica ERP you can assign specific roles for a particular domain user | Additional Information | 55

Additional Information

The following concept is outside of the scope of this course but may be useful to some readers. You can use the link below to get additional information.

Integrating Acumatica ERP with Microsoft Active Directory Federation Services The integration of Acumatica ERP with Microsoft Active Directory Federation Services (AD FS) provides centralized user and access management (by using Active Directory) and single sign-on (SSO) for your domain users. You can integrate Acumatica ERP with AD FS if you use an Acumatica ERP instance that is deployed on the Internet but not in the your organization’s intranet. With such integration in place, users of Acumatica ERP can access the instance with their domain credentials. You can integrate your Acumatica ERP instance with AD FS or Azure AD, but not with both. These two identity management systems are mutually exclusive because they use the same functionality to connect to Acumatica ERP.

For detailed information on the integration of Acumatica ERP with AD FS, see Integration with AD FS in the Acumatica ERP User Guide. | Lesson Summary | 56

Lesson Summary

In this lesson, you learned about integration between Acumatica ERP and Active Directory. Review Questions:

What are the benefits of AD integration in Acumatica ERP?
How would you locate AD settings in the web.config and enable them?
How do AD groups and Acumatica ERP roles work together to provide user access and authentication in Acumatica ERP?
What are the effects of turning off AD integration at a later date? | Lesson 5: Integration with Other Identity and Access Management Systems | 57