SoftwarePlanner Active Directory Authentication

(1)

This document provides an explanation of using

Active Directory with SoftwarePlanner.

User’s Guide

SoftwarePlanner Active Directory

Authentication

(2)

1

_{Using Active Directory with SoftwarePlanner}

Narrative

In some situations, it may be preferable to override SoftwarePlanner’s built in authentication, using a local Active Directory server to authenticate users instead. This document explains how

SoftwarePlanner’s Active Directory integration works and how to set it up for your enterprise installation of SoftwarePlanner.

What it does

A generic user account is created in AD, which is used by SoftwarePlanner to query AD (via LDAP) for users by EMAIL address. User accounts in AD must have the email field filled in or they will not be found. When a user attempts to log in we look up the user account in AD by email address, and if a match is found, we compare the password with a second query to AD. If the password comparison passes, the user is allowed to log into SoftwarePlanner. If the lookup fails, for any reason, any existing user account with that email address will be automatically locked out of SoftwarePlanner. You can have both SoftwarePlanner and ActiveDirectory users for SoftwarePlanner. This allows you to have local users log into SoftwarePlanner with their domain credentials and have external users (or customers) log into SoftwarePlanner without needing to be domain users. ActiveDirectory-enabled user accounts in SoftwarePlanner are “tagged” as AD-Login accounts using “User Variables”. When these log in, the system picks up this flag when validating the password and responds accordingly. If a user logs in with an email that is NOT found in SoftwarePlanner but IS found in AD, the user will be automatically added to SoftwarePlanner with “default” rights to a selected project. Using our Professional Services to apply customized logic, we can modify this process to grant users access to more than one project if desired.

What it does not do

Domain members are not automatically added to SoftwarePlanner when they are added to the domain. As soon as a new domain member attempts to log into SoftwarePlanner, they will be granted the default permissions for a default project. (Both options are customizable)

SP does not remember, store, or manipulate the domain password entered by the user. We validate the password that was entered on the login screen with LDAP queries, but we do not know what it is or store it in the SoftwarePlanner database.

SoftwarePlanner does not delete or disable a user the Active Directory when they are disabled in SoftwarePlanner.

We do not support conditional security in SoftwarePlanner based on AD container/unit. For example, we cannot make all users in the “marketing” container in Active Directory default to ProjectA in SoftwarePlanner, while users in the “development” container default to ProjectB).

(3)

2 Setting Up Active Directory Integration for SoftwarePlanner

Setting up SoftwarePlanner for Active Directory integration involves creating a domain user to query with and deciding on some default values for your SoftwarePlanner. Once you have this information, you insert the data as preferences into your SoftwarePlanner database (often called Pragmatic, or SoftwarePlanner) on your SQL server. Once the preferences have been inserted, a couple of quick tests will tell you if it is working correctly or not.

The Active Directory information that you need is as follows:

LDAP connection string

o In most cases this look something like one of the following:

 LDAP://DC1/DC=Company,DC=local

 LDAP://dc1.company.com/DC=Company, DC=local

o Your IT team or network administrator should be able to provide the LDAP connection string for you if you do not know it already.

Domain User Name for lookup user account

o This is a service account, or other user that SoftwarePlanner will use to look up users by email address in your active directory.

 In most cases it will be a value such as “Company\UserName”.

Domain Password for lookup user SoftwarePlanner DeptId

o Normally this is 8162, but your installation may be different. You can get this value from SoftwarePlanner by going to the Setup tab and clicking on Projects (Open & Create). From there, click on Choose Fields to add the Dept Id field for your project(s).

SoftwarePlanner AppCode

o Normally this is agSPEnt, but your installation may be different. You can get this value from the URL used to log in to SoftwarePlanner. In the screenshot below, the AppCode would be agSPPSC.

For SoftwarePlanner, you also need to decide on default values for the following items. These values can be changed for individual users at any time by an Administrator. These default values can also be changed later if needed.

(4)

3

Default project new domain users will be added to

o This will be the first project that new domain users will see when they log into

SoftwarePlanner. Depending on your security policies, this could be an active/working project, or it could be an empty project.

o You will need to know the exact NAME of the project, as it appears in SoftwarePlanner

Default security group that new users will belong to within the default project

o This is the security group that new domain users will belong to within the default project chosen above

Default Time Zone that users will belong to

o The full list of Valid time zones can be found in the SoftwarePlanner database by executing the following Query:

 SELECT Code FROM Validations WHERE ValidationType=’TimeZone’

 A few common values are

GMT-05 Eastern (US/Canada) GMT-06 Central (US/Canada) GMT-07 Mountain (US/Canada) GMT-08 Pacific (US/Canada)

Once you have the values for these 7 items, you will need to insert them into your SoftwarePlanner with the SQL on the next page. You need to replace the variable values in this script with the values from above.

Once you have replaced the values, your SQL Administrator or IT team should be able to execute the SQL on your SoftwarePlanner database.

(5)

4

--Add DeptSettings for AD-Sync.

DECLARE @Id int,

@AppCode varchar(100), @DeptId int,

@Value varchar(2000), @LDAP varchar(200),

@DefaultSecurityGroup varchar(35), @DefaultProject varchar(35),

@ADUser varchar(35), @ADPwd varchar(35), @TimeZone varchar(100)

--****** CHANGE THESE VALUES TO YOUR APPCODE AND DEPTID*******

SET @AppCode='agSPPSC'

SET @DeptId=8162

SET @LDAP='LDAP://servername/DC=domainname,DC=com'

SET @DefaultSecurityGroup='NoviceUsers'

SET @DefaultProject='YourProjectName'

SET @ADUser='DomainName\UserName'

SET @ADPwd='p@wd'

Set @TimeZone='GMT-07 Mountain (US/Canada)'

/* NOTE: to get a list of valid time zones use the following SQL SELECT Code FROM Validations WHERE ValidationType='TimeZone'

copy and paste an appropriate code into the value above */

--**************************************************************

EXEC sp_Add_Preferences @Appcode,0,0,

'ActiveDirectory-ConnectionInfo',@LDAP,24661,@DeptId ,@Id

'ActiveDirectory-AddUserDefaultTimeZone',@TimeZone,24661,@DeptId ,@Id

'ActiveDirectory-AddUserDefaultSecurityGroup',@DefaultSecurityGroup,24661,@DeptId ,@Id

'ActiveDirectory-AddUserDefaultProject',@DefaultProject,24661,@DeptId

,@Id

'ActiveDirectory-ADUsr',@ADUser,24661,@DeptId ,@Id

'ActiveDirectory-ADPwd',@ADPwd,24661,@DeptId ,@Id

--Insert the Person Variable record

IF NOT EXISTS (SELECT * FROM Validations WHERE

ValidationType='UserVariables' and Code='IsActiveDirectoryAccount') BEGIN

INSERT INTO Validations VALUES (@AppCode, 0, 'UserVariables',

'IsActiveDirectoryAccount', 'IsActiveDirectoryAccount',

NULL, NULL, 0, 'Y', 24792, GetDate(), GetDate(), 'N', NULL) END

(6)

5

Once the values have been inserted into the database, you can test the integration by entering the email address and domain password for a user that is NOT already in SoftwarePlanner and making sure that the system logs you in as this new user and that you are automatically dropped into the default project with the correct security rights.

To enable the Active Directory login for existing SoftwarePlanner users, you will need to go to edit the existing user in SoftwarePlanner. From the edit screen for the selected user, click on the User

Variables tab. Click on the Add New button to add a new User Variable. Select

IsActiveDirectoryAccount from the Variable Token Name choice list, and enter Y for Variable Value, then press Submit.

(7)

(8)

7

It is better to test the Active Directory integration with a user that does not already belong to SoftwarePlanner. As mentioned earlier, if the Active Directory lookup fails for any reason (invalid LDAP connection string, invalid lookup user credentials, connection failure, etc), the associated

SoftwarePlanner account will be disabled. If you are setting up the Active Directory with the only

active SoftwarePlanner login account, if that account is disabled you will not be able to log in to update settings or re-enable test users.

To re-enable a user that has been disabled, whether it was from with SoftwarePlanner or from the Active Directory integration, go to Setup -> Security ->Users. Click on the Actions menu and make sure that the “Show Deleted Users?” check box is checked.

(9)

8

Then either scan the list, or use Quick Search to locate the user. When you edit the user’s record you will see a “Restore this user?” check box at the bottom of the form. Check the box and press submit and the user will be restored. Whenever you restore a user, it is a good idea to check their security group settings for the projects that they belong to.

Once the preferences have been added to SoftwarePlanner, you can update the preferences (LDAP connection string, user name, password, Default Project, etc) by going to the Setup tab. From the Setup tab, expand System Configuration, and you will see “System Preferences”. Click on that, then click quick search and enter ActiveDirectory- and press submit.

Clicking on the Edit icon (looks like a green pen), will bring up the edit sheet for that preference allowing you to change the value.

After changing a system preference (or multiple preferences) it is best to log out of

(10)