Projectal includes built-in Single Sign-On (SSO) features to let your users log into Projectal and their other applications via a single email address or identity. 

SSO enables users of Projectal to securely log in and authenticate using your company's Lightweight Directory Access Protocol (LDAP) or Active Directory (AD) service. This saves the user from remembering multiple usernames and passwords, while still providing strong user authentication for your company. 

For your IT department, SSO is useful because all applications and accounts can be managed in one central secure location.

Projectal can be configured and connected to your company's LDAP or AD service to let your users log into Projectal using their existing login credentials used at your company.  This means they will not need to have separate user IDs and passwords for Projectal.  This is particularly useful for on-premises installations of Projectal.

Configuring LDAP / AD

Tip: These configuration steps only apply for on-premises installations of Projectal.  If your Projectal is hosted and managed by JanusKS, then contact the Projectal Support team to discuss how your LDAP / AD connection can be configured in Projectal.

To configure LDAP / AD support for your Projectal installation, you need to edit the Projectal properties file that is located on each Projectal API server.

1. On each API server where Projectal is installed, go the /data/projectal folder.
2. Edit the application.properties file using a text editor such as nano.
3. After making changes to the application.properties file, save your changes and then restart the API server using the following command: 

sudo systemctl restart projectal-web-api 

Sample Settings for Windows Active Directory (AD)

ldap.enabled=true 
ldap.url=ldap://192.168.0.9:389 
ldap.base.dn=cn=users,dc=EXAMPLE-COMPANY,dc=com 
ldap.username=CN=Administrator,CN=Users,DC=example-company,DC=com 
ldap.password=Password123456 
ldap.user.dn.pattern=(&(objectclass=person)(|(department=production)(department=finance))) 
ldap.login.attribute=userPrincipalName
ldap.firstname.attribute=givenName 
ldap.lastname.attribute=sn 
ldap.email.attribute=userPrincipalName 
ldap.profile.disable=useraccountcontrol 
ldap.accessPolicy=MANAGEMENT

Sample Settings for OpenLDAP

ldap.enabled=true 
ldap.url=ldap://192.168.0.235:389 
ldap.base.dn=ou=people,dc=example,dc=com 
ldap.username=cn=projectal_access,dc=example,dc=com 
ldap.password=Password123456
ldap.user.dn.pattern=(&(objectclass=person)(employeeType=manager)) 
ldap.login.attribute=mail
ldap.firstname.attribute=givenName 
ldap.lastname.attribute=sn 
ldap.email.attribute=mail 
ldap.profile.disable=pwdAccountLockedTime 
ldap.accessPolicy=PRODUCTION-TEAM

Important: Your company's LDAP / AD service must have first name, last name and email data attributes defined for each user that you wish to add into Projectal.  Users without these 3 data attributes will be skipped and not added as users into Projectal. 

ldap.enabled

Set this value to true to turn LDAP / AD authentication on.  

Set this value to false to turn LDAP / AD authentication off.

ldap.url

This is the URL location of your company's LDAP / AD service.  This setting is required.

Examples:

• ldap://192.168.0.235:389
• ldap://192.168.0.9:389

Tip: If no port is defined in the LDAP URL, then port 389 will be used.

ldap.base.dn

This is the root point of the directory for your company's LDAP / AD service where Projectal starts searching for users to add into Projectal.

Examples:

• ou=people,dc=example,dc=com
• cn=users,dc=EXAMPLE-COMPANY,dc=com

ldap.username

This is the account used to authenticate and permit Projectal to access to your company's LDAP / AD service.  This setting is required.

Examples:

• CN=Administrator,CN=Users,DC=example-company,DC=com
• cn=projectal_access,dc=example,dc=com
  

ldap.password

This is the password for the account used to authenticate and permit Projectal to access to your company's LDAP / AD service.  This setting is required.

Examples:

• Password123456

ldap.user.dn.pattern

This is the filter pattern that will be used to find and filter the users that you wish to be added into Projectal.  This setting is required.

Examples:

• (&(objectclass=person)(employeeType=manager))
• (&(objectclass=person)(|(department=production)(department=finance)))

Tip: To learn more about the syntax for writing LDAP search filters and see more LDAP filter examples, visit these resources: 
- How to write LDAP Search Filters
- Active Directory: LDAP Syntax Filters

ldap.login.attribute

This is the data attribute from your LDAP / AD service that represents the identifier of the user that they will use to log into Projectal.  This setting is required.

Examples:

• mail
• userPrincipalName

ldap.firstname.attribute

This is the data attribute from your LDAP / AD service that represents the first name of the user.  This setting is required.

Examples:

• givenName

ldap.lastname.attribute

This is the data attribute from your LDAP / AD service that represents the last name of the user.  This setting is required.

Examples:

• sn

ldap.email.attribute

This is the data attribute from your LDAP / AD service that represents the email address of the user.  This setting is required.

Examples:

• mail
• userPrincipalName

ldap.profile.disable

This is the data attribute from your LDAP / AD service that represents whether a user is disabled in your company's LDAP / AD server.  This setting is required.

If a user is disabled in your company's LDAP / AD, then Projectal will not add this user as a new user into Projectal.  If the disabled user already exists in Projectal, then the user will be updated to be also disabled in Projectal.

Examples:

• pwdAccountLockedTime
• useraccountcontrol 

ldap.accessPolicy

This is the access policy that Projectal will assign to users when new users are detected in your company's LDAP / AD service and are added into Projectal.  This setting is optional.

The value can either be blank or must match the name of an existing access policy found in the Management / Access Policies screen in Projectal.

If there is no access policy set (i.e. it is blank), then when adding new users from your company's LDAP / AD service, Projectal will assign the same access policy as the user that has System Administrator rights.

Tip: If you want new users in Projectal that have been added from your company's LDAP / AD service to have restricted access to certain features or data in Projectal, then it is recommended to create an access policy in Projectal with these restrictions, and then add the name of this access policy to this setting.  All new users added in Projectal from LDAP / AD will adopt this access policy and have restricted access to features and data in Projectal.

Examples:

• ADMIN
  
• MANAGEMENT
• PRODUCTION-TEAM
• <blank>

Synchronizing LDAP / AD in Projectal

After configuring LDAP / AD in Projectal, the next step is to synchronize Projectal with your LDAP / AD service in Projectal so that users are added into Projectal from your LDAP / AD service.  

To sync your LDAP / AD service in Projectal, your user account in Projectal needs to have the Sync LDAP / AD permission set in its user permissions.  To check this, go to the Users screen, edit the user and click the Customize button to check the user account's permissions.  The Sync LDAP / AD permission is found under the Users section.

Once your user account has the Sync LDAP / AD permission, then you will see the Synchronize LDAP / AD button displayed on the toolbar on the Users screen.  Click this button to synchronize your company's LDAP / AD service into Projectal.  Projectal will connect to your LDAP / AD service and find all users that match your LDAP filter.  New users will be added into Projectal.  Existing users will be updated.  Deleted users will be disabled.

Tip: From time-to-time, when you make user account changes in your company's LDAP / AD service, then click the Synchronize LDAP / AD button on the Users screen to update the user accounts in Projectal.

Tip: It is recommended to have at least one Projectal user account that is not authenticated via LDAP / AD services so that you can log into Projectal without using LDAP / AD.  This takes care of the situation when your LDAP / AD service may not is not configured correctly or not available and no one can log into Projectal to administer it.