TrueSight Capacity Optimization 10.x - LDAP Integration with Microsoft Active Directory. January 2017

Size: px

Start display at page:

Download "TrueSight Capacity Optimization 10.x - LDAP Integration with Microsoft Active Directory. January 2017"

Magdalen Kelly
6 years ago
Views:

1 TrueSight Capacity Optimization 10.x - LDAP Integration with Microsoft Active Directory January 2017

2 If you plan to use Capacity Views, or other views provided by TrueSight Presentation Server, don t waste your time with the LDAP setup, integrate the security by using Atrium SSO which is required by TrueSight Presentation Server. LDAP integration can be used only in a environment without views from TrueSight Presentation Server. The views available in TrueSight Presentation Server are different across the version please check relevant product version URL links are at the end of this document in Troubleshooting section. Please share this document with a Active Directory Domain administrator, to figure out the best setting which depends on the Active Directory Forest /Domain structure.

3 Acronyms used in the document TrueSight Capacity Optimization TSCO Microsoft Active Directory AD Microsoft AD Organization Unit - OU Windows Domain Controller DC LDAP Lightweight Directory Access Protocol LDAPS LDAP tunnel over SSL, requires certificate deployments on the DCs to listen on port 636

4 Chapters in this document 01 Overview and Prerequisites - Page 5 02 Consideration for LDAP Configuration Page Configuration Examples Page Troubleshooting Page Most common error and causes - Page 32

5 01 Overview & Prerequisites Overview

6 LDAP Integration Overview TSCO Application Service Windows Active Directory With LDAP integration the authorization remains in TSCO, the control access for groups ( TSCO Access Groups) and activity tasks (TSCO Roles) to domains in TSCO Workspace. The authentication, check for user and password is confirmed by the remote LDAP Server. The TSCO Application Service is using a simple LDAP bind to AD when a user logins to TSCO to verify if username and password matches. If the user account is locked in Active Directory, the user and password combination does not match, or External names are not set to match relevant AD groups, a login in TSCO is not possible. Multiple Login attempts with invalid user and password combination in TSCO may cause that the AD User can get looked if it exceeds numbers of Lockout Threshold in AD Domain Account Lockout Policies.

7 Prerequisite Organize groups in Active Directory UserA UserB Group If not taken in place organize the users in groups in Microsoft Active Directory. Multiple groups are in most cases used, at example a different group for users which act as product administrators, and a different group for users which have only limited access to into the product. Use separate groups for each set of user which should have access into the same area of the product, at example you should consider a separate group for users which have only access to a set of TSCO Domains in product workspace or only to a specific tab. Use separate groups also to limit a set of user activities, at example. Some users are only allowed to read reports, but are not allowed to create a reports, you should have a separate AD groups for the different requirements. Existing groups AD can be used if separated according the in-house requirements already.

8 TSCO - Prerequisite Roles Click on the Link of the role name to change activities. Administration > USERS> Roles To configure what activities AD groups are allowed to run in TSCO, at example Open Reports or View Analysis. Please review the relevant product documentation for more details on Roles and Activity. Multiple External names are separated with a ; ADMIN In the screenshot example the AD Group TSCO has all activity permission from the ADMIN role. REPORT_READER In the screenshot example the AD Group TSCOLE has 2 activity permission from the that role and can only read reports You may need higher number of Roles depending your environmental needs. Use the blue Pencil Button right to the Role to set the External name

TSCO - Prerequisite Edit Roles Administration > USERS> Roles Set the External Names matching the CommonName attribute of the group in AD Multiple External names are separated with a ; Don t forget to

9 TSCO - Prerequisite Edit Roles Administration > USERS> Roles Set the External Names matching the CommonName attribute of the group in AD Multiple External names are separated with a ; Don t forget to save the changes when done. For most environment you only need to set the external names and change the Activities permission if required, for other settings in most cases the defaults are used See relevant product documentation for more details

TSCO - Prerequisite Access groups Administration > USERS> Access groups To configure access to the entities in Workspace, to restrict access to Domains, Report Groups, and Views.

***ALLL*** is read only ***ALL*** Exist per default it has access to all existing entities in the environment and to everything which is created in future, recommended for administrators TSCOLE An

10 TSCO - Prerequisite Access groups Administration > USERS> Access groups To configure access to the entities in Workspace, to restrict access to Domains, Report Groups, and Views. Please see relevant product documentation for more details on Access Group. Multiple External names are separated with a ; Click on the Link of the access group name to change access in workspace. ***ALLL*** is read only ***ALL*** Exist per default it has access to all existing entities in the environment and to everything which is created in future, recommended for administrators TSCOLE An new created access group example configured only for access to Reports You may need higher number of Access Groups depending your environmental needs. Use the blue Pencil Button right the Access group to edit the group and set the External name

TSCO - Prerequisite Edit Access Groups Administration > USERS> Access groups Set the External Names matching the CommonName attribute of the group in AD Multiple External names

11 TSCO - Prerequisite Edit Access Groups Administration > USERS> Access groups Set the External Names matching the CommonName attribute of the group in AD Multiple External names are separated with a ; Don t forget to save the changes when done. For most environment you only need to set the external names. See relevant product documentation for more details

12 02 Consideration for LDAP configuration Pre-determine right settings

13 LDAP Bind login under User or use a separate account for bind The product is using a LDAP/LDAPS Simple Bind to Services Active Directory with the CommonName Agent (using or UserPrincipalName tunnel) LDAP Attribute from the login user to search for the related groups by using the DistinguishedName. Alternatively a separate services account with the DinstinguishedName and password can be set. Bind directly with login user More flexible, less maintenance Per default each user account is allowed to bind to Activate Directory Recommended approach, unless required for security. Bind under separate service account Use DistinguishedName and password as bind account, if the password changes in AD with password policy, no Windows AD User can login into the product console until the password is synched To avoid issues with password changes in Windows AD with a separate bind account it is recommended to Bind directly with the Login user, unless a in-house security policy requires a services account

14 Bind with CommonName or UserPrincipalName The best setting depends on the Windows Active Directory Forest / Domain and Services Organization Agent Unit (using (OU) tunnel) structure CommonName Good for domains where all users and groups are stored in the same Organization Unit structure root like CN=Users,DC=Domain,DC=com or below a different root tree. Use with multiple domains in TSCO for user access for users from different Windows Domains, in different forests or different domain trees May not be comfortable the CommonName Attribute contains spaces UserPrincipalName Good for large with Child domains if all users have the same UserprincipalName prefix configured. To avoid long response times when using Universal Groups and different AD Domain Sites, bind to Domain Controller hosting the Global Catalog Role ( LDAP 3668, LDAPS 3269) instead (LDAP 389, LDAPS 636) ports.

15 Bind with samaccountname The best setting depends on the Windows Active Directory Forest / Domain and Services Organization Agent Unit (using (OU) tunnel) structure samaccountname TSCO 10.3 doesn t support the bind with the UserPrincipalName Use it if CommonName Attribute contains spaces, or if CommonName and samaccountname have a different naming convention. When using this approach a separate account for the bind is required A change on the Search to retrieve user account is required. See example in Configuration Example Chapter.

16 LDAP Configuration Settings Overview Page 1 Administration > SYSTEM > Global configuration, Authentication Tab Services Agent (using tunnel) Default Domain / Domain List If a Default domain is specified, then users can log in with just their username. If no Default domain is specified, then users must always log in using the "domain\user" syntax if CommonName bind is used. Bind Method Bind directly with Login User, or define a separate search account. LDAP Context Set the root context of the domain to build the DistinguishedName, example dc=domain,dc=com or dc=child,dc=domain,dc=com LDAP User Attribute / LDAP Group Name In almost most environments this should be set to cn, short name of CommonName attribute. LDAP User Query Used to build the search path for users and groups together with the LDAP Context: cn=users Would search for users and groups under cn=users,dc=domain,dc=com

17 LDAP Configuration Settings Overview Page 2 Administration > SYSTEM > Global configuration, Authentication Tab Services LDAP Fullname Attribute Use a meaning full attribute which shows more details of the user, in most cases the displayname attribute can be used. LDAP User Attribute The mail attribute is used per default, if no mail attribute is set in Active Directory user UserPrincipalName, which provides an attribute value in format. LDAP Description Attribute For most environment the description attribute is a good candidate. LDAP GroupName Attribute Used to find the user account in the groups, which is the member attribute for the most environments. LDAP Group Members Matching Mode Used to find a matching patter for a user in a group, per default the distinguished name attribute is used which should work for most environments.

18 03 Configuration Examples Examples for different environments

19 Global Configuration - Start Administration > System > Global Configuration Advanced Settings are in most environments not required for the Authentication on Global Configuration, keep it Basic to avoid confusion with settings which are not needed. Local Authentication is enabled to switch to LDAP select LDAP to open the configuration settings.

20 Global Configuration Add Domain List Administration > System > Global Configuration The first step is to add a LDAP Domain List matching the Windows AD name in which users and groups are located. You can add multiple Domain List to connect to different Windows AD domains. In the examples we work with a Windows AD with root prefix DC=bmmsup,DC=xy and with a second domain tree in same the forest DC=bmmsup,DC=net.

$LDAP was set as Authentication mode. The Domain to create is called BMMSUP, and set as default domain, useful to avoid login with a domain prefix BMMSUP\username.$

21 Global Configuration - Overview Administration > System > Global Configuration Advanced Settings are in most environments not required, keep it Basic to avoid confusion unless required. LDAP was set as Authentication mode. The Domain to create is called BMMSUP, and set as default domain, useful to avoid login with a domain prefix BMMSUP\username. Set it to LDAP managed, the Native mode should not be used.

Global Configuration Users are in default AD OU structure cn login Administration > System > Global Configuration A default OU structure is used all Users are stored below the default container:

22 Global Configuration Users are in default AD OU structure cn login Administration > System > Global Configuration A default OU structure is used all Users are stored below the default container: CN=Users,DC=bmmsup,DC=xy Please take care about the LDAP User Attribute, it is set to UserPrincipalName in this screenshot because there is no mail attribute set in this test AD. The default attribute value is mail If the CommonName LDAP attribute contains spaces in AD, the user must login with the space in the name to TSCO

Global Configuration add second Domain List - Overview Administration > System > Global Configuration You can add a second domain if required for Windows domains from different forests, domain trees,

23 Global Configuration add second Domain List - Overview Administration > System > Global Configuration You can add a second domain if required for Windows domains from different forests, domain trees, trusted domains. BMMNET was just added here by using the ADD button BMMNET CN=Users,DC=bmmsup,DC=net and BMMSUP CN=Users,DC=bmmsup,DC=xy are different domain trees in the same forest. The new domain you added it listed on the bottom and you need to scroll down, be careful to net edit an existing domain when you add a new. For BMMSUP Users, because it is default the user can login with the cn attribute value only users from BMMNET need to login with the LDAP Domain List name as a prefix like BMMNET\username.

Global Configuration add second Domain List - Configuration Administration > System > Global Configuration Before edit anything in the second domain verify that you scrolled down on the configuration

24 Global Configuration add second Domain List - Configuration Administration > System > Global Configuration Before edit anything in the second domain verify that you scrolled down on the configuration dialog additional domains will be added always to the bottom of the configuration, enable some option may cause the GUI interface scrolls You can add a second domain with commonname also to a different OU structure, or you can use it with UserPrincipalName logins. The main point to consider is just that you login as a user from AD set as Default Domain List without the Domain List Prefix.

Global Configuration Users in non-default AD OU structure CommonName login Administration > System > Global Configuration In this examples the users are not located in default OU structure the users

25 Global Configuration Users in non-default AD OU structure CommonName login Administration > System > Global Configuration In this examples the users are not located in default OU structure the users are located in OU=TSCO,DC=BMMSUP,DC=xy All users below that OU level are allowed to login, Users which are stored in the default OU structure CN=Users,DC=BMMSUP,DC=xy CANNOT login. You can also set the OU level to a deeper lever the LDAP referral queries are working recursively down and not up to the path. In fact the only change in this page is that the LDAP Query Attribute was changed from CN=Users to OU=TSCO. LDAP Context + LDAP Query Attribute need to point to the OU structure where the user are located

Global Configuration Bind with UserPrincipalName attribute Administration > System > Global Configuration The main difference is the LDAP Authentication Using UserPrincipalName option, you are

26 Global Configuration Bind with UserPrincipalName attribute Administration > System > Global Configuration The main difference is the LDAP Authentication Using UserPrincipalName option, you are required to set the Upn postfix This approach can also used if the cname attribute contains space, in some environments cname and samaccountname which is used by Windows login does not match where as the postfix of the UserPrincipalName does match better, the users can use the same user login string as on Windows. A requirement is that users in the Domain List have the same UserPrincipalName postfix, at example username@bmmsup.xy. You can set this as the default Domain List.

Global Configuration Bind with samaccountname attribute Administration > System > Global Configuration It is required to use a separate account for the Bind Method and it is required to change the

27 Global Configuration Bind with samaccountname attribute Administration > System > Global Configuration It is required to use a separate account for the Bind Method and it is required to change the Search to retrieve user account. This approach can also used if the cname attribute contains space, in some environments cname and samaccountname which is used by Windows login does not match the users can use the same user login string as on Windows. A requirement is to use a Search Account please consider if the password of this account does change it must be changed in TSCO. Change the Search to retrieve user account, the default is not using. (samaccountname=%username%)

28 04 Troubleshooting Additional Tips to debug issues

29 Logfile - $BCO_INSTALL/web/log/cpit.log The console shows in most cases only, the log per default may not show more, it might be required to increase logging to DEBUG level Services BCO_WEB_WARN301 - Inexistent user or wrong password. Please check your credentials. Agent (using tunnel) Enable debug logging to see more details: Backup file $BCO_INSTALL/web/conf/log4j.conf open it with a editor and locate the line: log4j.logger.com.neptuny=info, cpit Change this line to: log4j.logger.com.neptuny=debug, cpit A services restart is not required, don t forget to restore the file once the implementation is conplete

30 Verify attributes in Active Directory You can use different tools to verify the attributes in Active Directory, if assistance from BMC Support is required please provide outputs from dsget/dsquery commands run on a DC or on a PC with RSAT tools installed. Provide output from the users by using the cname attribute which cannot login, replace username dsquery user -name username dsget user -dn -upn -samid -disabled dn samid upn disabled CN=user,CN=Users,DC=bmmsup,DC=xy user user@bmmsup.xy no Provide output from the group by using the cname attribute which are set as external name, replace groupname dsquery group -name groupname dsget group -members -expand CN=username,CN=Users,DC=bmmsup,DC=xy CN=username2,CN=Users,DC=bmmsup,DC=xy The output can become quite large, so please > redirect it to a test file after review the output, if you copy the commands to a cmd.exe shell take care about the - in the command some document reader versions concert the to a non ASCII character which can cause problems in the command line, so you may review the exact command in a simple txt file and replace the with a simple - in Notepad.

31 commands to determine connection issues On the TSCO Application Server you can run various commands to determine issue with connection to the hostname and port used as LDAP Provider URL ping the hostname with ping command used in LDAP Provider URL attribute > ping hostname.domain.com PING hostname.domain.com ( ) 56(84) bytes of data. 64 bytes from hostname.domain.com ( ): icmp_seq=1 ttl=64 time=0.040 ms Use telnet command if available > telnet hostname.domain.com 389 Trying Connected to hostname.domain.com Escape character is '^]'. If you see this output it connects well, if not you get a connection refused error ( wrong port) or Unknown host for wrong hostname You can leave the telnet session with strg +c on your keyboard. Use wget command if available > wget hostname.domain.com:389 This command output is looping on successful connect, stop that with strg + c from your keyboard, you get a you get a connection refused error ( wrong port) or Unknown host for wrong hostname on unsuccessful connect.

32 nslookup command to verify your DCs from DNS On the TSCO Application Server you can nslookup command to get all DC from a DNS Domain if registered in DNS as SRV Records use the domain postfix you use in the LDAP Provider URL attribute to figure out which hostnames are DCs from the used DNS Domain. Replace to bmmsup.xy string on the command to match your DNS DomainName [user@hostname ~]$ nslookup -type=srv _ldap._tcp.bmssup.xy ;; Truncated, retrying in TCP mode. Server: Address: #53 _ldap._tcp.domain.com _ldap._tcp.domain.com service = dc1.bmmsup.xy service = dc2.bmmsup.xy This command output shows that there are 2 DCS configured in DNS, if you have none default LDAP ports 389 is a different number.

33 BMC TrueSight Capacity Optimization Documentation BMC TrueSight Capacity Optimization 10.7 BMC TrueSight Capacity Optimization 10.5 BMC TrueSight Capacity Optimization 10.3 BMC TrueSight Capacity Optimization 10.0

34 05 Most common errors and causes In $CPIT_INSTALL/web/log/cpit.log

35 TSCO server cannot recolve DC hostname The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: FAILED [http-bio exec-7]- BCO_WEB_FAIL102 : LDAP server ldap://hostname.bmmsup.xy:389 is not responding. StackTrace: javax.naming.communicationexception: hostname.bmmsup.xy:389 Caused by: java.net.unknownhostexception: hostname.bmmsup.xy The cause is that the TSCO server cannot resolve the hostname of the DC via DNS please try to ping the hostname from the TSCO server and check with nslookup if the hostname points to the right IP of the DC to connect to.

36 Remote Hostname is not listen on the configured TCP/IP Port. The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: > FAILED [http-bio exec-7]- BCO_WEB_FAIL102 : LDAP server ldap://hostname.bmmsup.xy:389 is not responding. StackTrace: javax.naming.communicationexception: hostname.bmmsup.xy:389 > [Root exception is java.net.connectexception: Connection refused] hostname.bmmsup.xy:389 The cause is that that the hostname is not a DC or a Firewall is blocking communication. You can try a connection with telnet or wget to connect to hostname + port, this fails also. Check with the Domain Administrator if the hostname used is a domain controller. And check with nslookup command from this documentation to get DC from a DNS Domain if registered properly in the DNS Zone.

37 Wrong LDAP Provider URL Format The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: >ERROR [http-bio exec-9]- BCO_WEB_ERR011: Impossible to check LDAP user credentials StackTrace: javax.naming.invalidnameexception: Invalid name: bmmsupb1.bmmsup.bmmsup.xy:389 at javax.naming.ldap.rfc2253parser.doparse(rfc2253parser.java:111) at javax.naming.ldap.rfc2253parser.parsedn(rfc2253parser.java:70) Check the format of the LDAP Provider URL setting for missing, a slash / or colon : ldap://<hostname>:<port> or ldaps://<hostname>:<port> are valid settings.

38 Wrong - LDAP Context configured The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: > LDAP bind with security principal: cn=user,cn=users > Invalid credentials for LDAP user > ERROR [http-bio exec-6]- BCO_WEB_ERR011: Cannot login user user, please check your configuration StackTrace: com.neptuny.cpit.acl.ldapusermanagmentexception: It's not possible to find the LDAP user for get its attributes. Context:dc=bmmsup,dc=net Filter:(&(objectClass=*)(cn=user)) Please check the LDAP Context it does not match the domain used to connect

39 Wrong - LDAP User Query configured The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: > Logging in as user username > LDAP bind with security principal: cn=username,cn=users > Invalid credentials for LDAP user > Login failed for user username > BCO_WEB_WARN301: Inexistent user or wrong password for user username Probably the cause that the user is not stored in the configured Organization Unit cn=users in this example. Use the dsquery dsget commands examples to determine the right setting from page 28.

40 LDAPS /LDAP Protocol mixup The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: > FAILED [http-bio exec-10]- BCO_WEB_FAIL102: LDAP server ldaps://bmmsupb1.bmmsup.xy:389 is not responding. StackTrace: javax.naming.communicationexception: simple bind failed: bmmsupb1.bmmsup.xy:389 [Root exception is java.net.socketexception: Connection reset] Check the format of the LDAP Provider URL it connects to ldap on port 389, but defined in the URL is ldaps as a protocol.

41 LDAP / LDAPS Protocol mixup The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: > FAILED [http-bio exec-7]- BCO_WEB_FAIL102: Please check LDAP server url StackTrace: javax.naming.serviceunavailableexception: bmmsupb1.bmmsup.xy:636; socket closed at com.sun.jndi.ldap.connection.readreply(connection.java:454) Check the format of the LDAP Provider URL have you defined ldaps as the protocol on the URL? Port 636 is only for LDAP protocol and requires a certificate infrastructure, if not available use Port 389 for LDAP.

42 External Names are not set in TSCO correctly The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: > Logging in as user username > LDAP bind with security principal: cn=theuser,cn=users > Logged on LDAP as user cn=theuser,cn=users > LDAP bind successful > Login failed for user "TheUser". Not authorized The User is not in a Windows AD group matching the External names for TSCO Roles and Access Groups. Please use dsquery/dsget commands from this document to verify the group membership of this user and if he is in a group where you set the External names for in TSCO.

43 No mail attribute available The console shows this error: Agent (using tunnel) Services BCO_WEB_ERR011 - Console reported a generic issue in the component. The cpit.log shows: > > BCO_WEB_ERR011: [Authorizator] Error in login > StackTrace: com.neptuny.cpit.acl.ldapusermanagmentexception: Value of "mail" is empty (or attribute doesn't exist). The mandatory, please check LDAP configuration.# The cause is that the mail attribute is blank in Active Directory, you can use UserPincipalName which is provided in format, similar error might happen for other attributes if blank in Active Directory

44 Wrong - certificate in truststore with LDAPS The console shows this error: Services Agent (using tunnel) BCO_WEB_WARN301 - Inexisting user or wrong password. The cpit.log shows: PKIX path building failed: sun.security.provider.certpath.suncertpathbuilderexception: unable to find valid certification path to requested target. The certificate cannot be downloaded from the DC, please double check if LDAPS is running on the configured LDAP Provider URL and Port on the remote target and if LDAPS is available on the DC at all. Get in touch with BMC Support if you encounter this issue.

Managing External Identity Sources

Managing External Identity Sources CHAPTER 5 The Cisco Identity Services Engine (Cisco ISE) integrates with external identity sources to validate credentials in user authentication functions, and to retrieve group information and other