Password Management

Overview

Password Management is used to administer requirements and other policies about user passwords in Sugar. Sugar allows administrators to set up system-generated passwords versus manually created passwords for new users, failed login lockout attempts, and configure the email templates used to send password information to users. Password management is not used to change users' passwords, which can be done via their User Profile.

Note: For instances that use SugarIdentity, an administrator will need to access SugarIdentity to configure password requirements as well as set up LDAP or SAML authentication.

Password Requirements

The Password Requirements panel lets you configure minimum and maximum lengths of passwords, as well as what characters are required in passwords. Filling in either of the first two fields, Minimum Length and Maximum Length, will force a requirement for your users to have passwords be more than or less than a given amount of characters. Additionally, use any of the four checkboxes to force character requirements on users' passwords. This can force users to include upper case letters, lower case letters, numbers, or special characters in their passwords. Please note that the configured password requirements also apply to the Sugar Portal and must be respected when the portal user's password is created or changed.

Note: For instances that use SugarIdentity, password requirements are configured in SugarIdentity.

Advanced Options

You can also specify words or other strings that are not allowed in a password, called Regex Requirements. The configurations for Regex Requirements are found in the Advanced Options section of the Password Requirements panel.

Note: For instances that use SugarIdentity, regex password controls are not available.

To set a Regex Requirement, type in code of characters that are not allowed. In the Regex Description field, write a message to users that will show when they try to edit their passwords, explaining what strings are not allowed. For more information on Regex usage, please review the Regular Expressions website at http://www.regular-expressions.info/.

Some examples of regular expressions in password rules are listed below:

Sample Expression	Password Rule
Sugar	Password cannot contain the word Sugar.
([A-Za-z0-9])\1	Password cannot repeat a letter or number consecutively; for example, AA or 88.
([a-zA-Z]){4,}	Password cannot repeat any two consecutive letters; repeat characters or letters must be separated by a special character such as %.
[ \t]	Password cannot contain spaces and tabs.
[@#$]	Password cannot contain @, #, or $.

System-Generated Passwords

When enabled, the System-Generated Passwords feature will allow users to receive a randomly generated password via email. This functionality is utilized either when a new user is created or when an administrator activates the Reset Password button in the user's profile.

Note: For instances that use SugarIdentity, the System-Generated Passwords feature is not available.

The two requirements to utilize system-generated passwords are:

A user has a valid primary email address configured in their User Profile.
A system outbound email server (SMTP) is configured in Email Settings.

For security reasons, when the System-Generated Passwords feature is enabled, you also have the option to set an expiration for the system-generated password. You can specify when the temporary password expires, either after a certain amount of days, months, or weeks, or after a specified number of logins. Simply click the radio button next to the expiration you would like to use and enter the login or length of time variable as necessary, or click "None" for the password to never expire. Once the temporary password expires, users will see a message upon login, informing them that the password has expired and to create a new password. The user will need to enter the temporary password along with the new password and confirm the password as well.

User Reset Password

The forgot password feature allows administrators to enable the Forgot Password link to display in the Sugar login window. If a user does not remember their password, they can click this option, enter their user name and their primary email address in Sugar, and a Reset Password link will be emailed, guiding them through the process to reset their forgotten password. For more information on how a user resets his or her password, please view the Getting Started documentation.

Note: For instances that use SugarIdentity, the "Forgot Password?" link is available on the Sugar login screen, but the feature cannot be configured.

The two requirements to utilize Forgot Password feature are:

A user has a valid primary email address configured in their User Profile.
A system outbound email server (SMTP) is configured in Email Settings.

Honeypot Validations

Honeypots are a non-intrusive method of human form submission confirmation that is more effective than traditional CAPTCHA. Enabling the honeypot validation option will add an invisible input field to the Forgot Password form which only bots reading the HTML will be able to see. When the bots fill in the honeypot field, Sugar knows to disregard the submission since it was not created by a human, thus preventing unauthorized access to your Sugar instance.

Note: For Sugar instances that use SugarIdentity, Honeypot validation is not available.
PasswordMgmt HoneypotValidations

Email Templates

Sugar comes standard with two password templates. One is for the System-Generated Password emails that are sent out, and the other is for the Reset Password email. The templates are editable through Password Management and new ones can also be created. To create a new version of either template, click the Create button on the specific line. To edit the existing template, click the Edit button on the specific line.

Note: For instances that use SugarIdentity, email templates cannot be created or edited.

Templates can also be viewed via the Emails module by navigating to the Email Templates list view. The templates are easily found as the Type is blank, whereas any other template will be either a Campaign, Email, or Workflow template. For more information on Email Templates, please review the appropriate section of the application guide.

Note: If you choose to create your own templates to send passwords, copy the variables provided in the default template. The variables "$contact_user_link_guid" from the "Forgot Password Email" and the " $contact_user_user_hash" and "$config_site_url" are not available from the variable dropdowns when creating the templates.

User-Generated Password Expiration

Sugar can force users to create new passwords after a given period. Admins can configure this for either specific amounts of time in days, weeks, or months, or after a specific amount of logins. To configure a password expiration, select the radio button next to the expiration period you would like to use and enter the timeframe or amount of logins that the user will be allotted. Once the password expiration is reached, users will see a message upon login, informing them that their password has expired and to create a new password. The user will need to enter their current password along with their new password and confirm the password as well.

Note: For instances that use SugarIdentity, password expiration rules are configured in SugarIdentity.
pword-expire

Login Lockout

To prevent unauthorized logins, Sugar includes a configurable lockout function. This means that you will define a specific amount of unsuccessful attempts that a user name can be used to log in before the user name will not be able to log in. You also configure a given amount of time before the restriction is listed in either minutes, hours, or days. To configure Login Lockout, click the radio button next to "Lockout users after {blank} unsuccessful login attempts", fill in the maximum number of attempts allowed and define the timeframe.

Note: For instances that use SugarIdentity, login lockout rules are configured in SugarIdentity.
login-lockout-77

Note: When a user has been locked out, the user must wait until the given timeframe has passed. The only way to manually allow a user to log back in is by clicking the Reset User Preferences button in the user's profile.

External Authentication

Sugar can respect external authentication protocols (i.e., LDAP and SAML) to give users a seamless login process via single sign-on (SSO) services. LDAP and SAML configuration options are located in the last two panels of the Password Management page. Click the checkbox next to the external authentication type that you would like to enable. Upon selection, the page's contents will refresh and the chosen protocol will supersede any other Password Management settings.

Note: For instances that use SugarIdentity, LDAP and SAML authentication are configured in SugarIdentity.

Note: If a user logs out of their single sign-on account from outside of Sugar, they will continue to be logged into Sugar.
enable-ldap-saml

The following sections explain LDAP and SAML options in more detail.

Note: Team Management and Role Management are still taken into account when External Authentication is active.

LDAP

Sugar can be configured to accept Lightweight Directory Access Protocol (LDAP) authentication if your organization has implemented LDAP or Active Directory authentication. When users in your system attempt to log into Sugar, the application will authenticate their credentials against your LDAP directory or Active Directory. If authentication is successful, the user is granted access to Sugar. If the authentication is unsuccessful, Sugar will then attempt to verify the provided credentials against its own database of valid user names and passwords.

Before proceeding with the configuration steps, you must first add a user to your Active Directory account for the purpose of authenticating from Sugar to Active Directory to read the LDAP. Make this user a managed service account (MSA) with read-only access to Active Directory. For more information on creating an MSA, please refer to the Managed Service Accounts: Understanding, Implementing, Best Practices, and Troubleshooting article on Microsoft's support site. For more information on configuring the Active Directory, please refer to the Microsoft's support site.

Use the following steps to configure LDAP authentication for instances that do not use SugarIdentity:
Note: For instances that use SugarIdentity, configure the LDAP authentication in SugarIdentity.

Navigate to Admin > Password Management and enable the checkbox next to "Enable LDAP Authentication" in the LDAP Support section.
Complete the fields with information specific to your LDAP or Active Directory account.
Click "Save".

Once you have completed the form, you will then need to enable LDAP for users by navigating to Admin > User Management, selecting the desired user, then clicking the Advanced tab in their user profile. Enable the "LDAP Authentication Only" checkbox, then click "Save".
PasswordManagement_UserProfile_Advanced_LDAPAuthenticationOnly

Sugar will synchronize the user's Active Directory user name and present the password on the LDAP port. When the user next logs in to Sugar, they will enter their Active Directory username and password.

If the Active Directory authentication server is behind a corporate firewall and your instance of Sugar is hosted in our cloud environment, then refer to the Configuring Your SMTP Server to Work With SugarCloud article to ensure the appropriate IP range is open on your firewall to allow communication with the Active Directory server. A rule will need to be created allowing the LDAP bi-directional communication for the necessary IP range. This can be the standard LDAP port 389 or you can use LDAP over SSL.

LDAP Fields

Fill in the appropriate options in the following fields, and then click "Save" to commit the changes. The following are suggested values for each field, but these may vary depending on your LDAP configuration.

Field	Suggested Values	Description
Authentication	Enter "username@MYSERVER.MYDOMAIN.com" or "domain\\userfirstname.userlastname" for the User Name, and the corresponding Password. Note: The latter username format requires double backslashes after the domain. Sugar will automatically remove one backslash upon Save.	Check this box to enable the User Name and Password fields. Note: You must add a service account user (read-only access) to your Active Directory to authenticate via Sugar.
Auto Create Users	Typically, this box remains disabled.	Select this checkbox to create the username in the Sugar database if it does not already exist. Note: When enabled, a Sugar user is created for every LDAP user logging into the application for the first time. This will occupy an active Sugar license for each created user. Keep this option disabled if you do not wish to create AD users in Sugar.
Bind Attribute	For Active Directory, enter `userPrincipalName`.	This is what is used for the Active Directory and is a case-sensitive value.
Enable LDAP Authentication		Uncheck this box if you would like to disable LDAP in your instance.
Encryption	Select "StartTLS" or "LDAPS" if the LDAP server supports it. Select "none" for no encryption.	Select the appropriate option from the dropdown to use StartTLS, LDAPS, or no encryption when connecting to the LDAP server.
Encryption Key		If you are using LDAP with SOAP, enter the encryption key to encrypt user passwords in the Sugar Plug-in for Microsoft Outlook. Note: The "php_mcrypt" extension must be enabled in the php.ini file.
Group Membership	Group DN: Enter the group DN name. ou=groups dc=example dc=com Group Name: Enter the group name. cn=sugarcrm User Attribute: A unique identifier used to check if the user is a member of the group. uid Group Attribute: The attribute of the group that will be used to filter against the User Attribute. MemberUid	Select this checkbox if you wish to specify that the user is a member of a specific group.
Login Attribute	For Active Directory, enter `sAMAccountName`.	This is what is used for the Active Directory and is case-sensitive.
Port Number	Enter "636" if using LDAPS encryption. Enter "389" if using "StartTLS" or no encryption.	Enter the default port number.
Server	Enter MYSERVER.MYDOMAIN.com.	Enter the FQDN of your Active Directory Server which should be your Domain Controller.
User DN	Enter ou=people, dc=example, dc=com.	Enter the user DN name.
User Filter	Enter `is_user_id=1`.	Enter any additional parameters to apply when authenticating users.

SAML

Sugar can be configured to accept Security Assertion Markup Language (SAML) for single sign-on if it is implemented at your organization. When users in your system attempt to log into Sugar, the application will authenticate them against SAML. If authentication is successful, the user is granted access to Sugar. If the authentication is unsuccessful, Sugar will then attempt to verify the provided credentials against its own database of valid user names and passwords. Sugar supports the use of SAML version 2.0.

Note: For instances that use SugarIdentity, SAML is configured in SugarIdentity.

Use the following steps to configure SAML authentication in Sugar:

Navigate to Admin > Password Management and place a check in the "Enable SAML Authentication" box in the SAML Authentication panel.
Enter appropriate values in the fields on the SAML Authentication page. If you have downloaded a metadata file from the identity provider (e.g., Okta, Google, ADFS), then skip to step 3.
If you have obtained a metadata file from the identity provider (e.g., Okta, Google, ADFS), then you can import the file by clicking the "Import IdP Metadata File" button. Locate the metadata file you saved then click "Open". Certain fields (e.g., Login URL, SLO URL, Entity ID, X509 Certificate) on the page will be auto-populated with data from the file. Optionally, complete any other desired fields on the configuration page based on your needs.
Note: If you are using Okta with single logout enabled, then you will need to complete the "Sign Logout Request", Request Signing Private Key", and "Request Signing Certificate" fields in order to digitally sign the logout request.
Once the necessary fields have been completed, click "Save" to preserve the settings.

When using ADFS, you will need to export an XML metadata file containing the SAML settings which you will need in order to configure a new trust relationship between Sugar and ADFS to allow communication between the two services. Simply click the "Export Metadata File" button to download the necessary file. Please note that you will only be able to export a file if the required fields have been completed and saved. Once you have the metadata file, follow the steps in the Configuring SSO With Active Directory's ADFS article to configure a new ADFS trust relationship.

Please refer to the SAML-Toolkits example for more information on how to configure advanced SAML connections.

SAML Fields

The available fields to configure on the SAML Authentication page are as follows:

Field	Description
Enable SAML Authentication	Uncheck this box if you would like to disable SAML Authentication in your instance.
Login URL	Enter the SAML URL for authentication. Note: This is the path to the SAML server to which you are authenticating.
SLO URL	Enter the single logout endpoint to which Sugar will send logout requests. When Sugar sends a logout request to the identity provider (e.g., Okta), it will extend that request and terminate active sessions for all other service providers that are sharing the session established via SAML. Note: Single logout requests can be initiated from either the identity provider or Sugar.
Entity ID	Enter a valid URI for the IdP (identity provider) entity. Note: Sugar will only accept SAML assertions from this ID.
SugarCRM Entity ID	Enter a valid URI for the service provider entity.
X509 Certificate	Enter the SAML X509 certificate public key.
Auto-create user	Check this box to automatically create a new username in the Sugar database if it does not already exist. When enabled, a new Sugar user is created for every SAML user logging into the application. Note: This will occupy an active Sugar license for each created user.
Load login screen in same window to avoid pop-up blocking	Enable this option to load the SAML login screen in the current window to prevent pop-up blockers from preventing single sign-on.
Request Signing Private Key	Upload the PEM file containing the private key to be used to sign the AuthN and Logout requests. Note: The private key must be uploaded in order to sign the logout request, logout response, and/or AuthN request.
Request Signing Certificate	Upload the CRT file containing the X.509 certificate to be used to sign the AuthN and Logout requests. Note: The certificate should match the uploaded private key.
Request Signing method	Select the digital signing method for the logout request, logout response, and/or AuthN request. The recommended options are either "RSA-SHA256" or "RSA-SHA512".
Sign AuthN Request	Check the box to sign the AuthN request using the private key and certificate. Note: The "Request Signing Private Key", "Request Signing Certificate", and "Request Signing method" fields must be completed in order to sign the AuthN request.
Sign Logout Request	Check this box to sign the logout request using the private key and certificate. Note: The "Request Signing Private Key", "Request Signing Certificate", and "Request Signing method" fields must be completed in order to sign the logout request.
Sign Logout Response	Check this box to sign the logout response using the private key and certificate. Note: The "Request Signing Private Key", "Request Signing Certificate", and "Request Signing method" fields must be completed in order to sign the logout response.

If you are using OneLogin, please ensure that only the email address user field is mapped to Sugar's email address field in OneLogin's parameters configuration. Mapping to other fields such as user name is not supported and may prevent authentication.

Note: You must disable the Forgot Password option if you are using SAML authentication.

Setting User Passwords

Administrators have the option to manually set or reset user's passwords as need be. Setting a regular user's password is done simply through the Users module via Admin > User Management. This method will vary depending on the System-Generated Passwords option. For more information on changing a user's password from the Users module, please review the Resetting User Passwords section of the Users documentation.

Note: For instances that use SugarIdentity, administrators will not be able to manually change a user's password via the user's profile. But administrators can send password reset emails to users via SugarIdentity.