ASSO integration in Windows Active Directory for …...If a product from TrueSight family is integrated into Windows Active Directory, for example TrueSight Capacity Optimization,

ASSO integration in Windows Active Directory for TrueSight 10

BMC - SupportTechnical Support Analyst

Acronyms Used in this documentation

ASSO – BMC Atrium Single Sign OnTrueSight Capacity Optimization – TSCOMicrosoft Active Directory – ADMicrosoft Windows AD Organization Unit - OUWindows Domain Controller – DCLDAP – Lightweight Directory Access ProtocolLDAPS – LDAP tunnel over SSL , requires certificate deployments on the DCs to listen on port 636DN - DistinguishedNameCN - CommonNameDC - Domain Controller

Chapters in the documentation

1. Prerequisites and Overview

Brief overview for perquisites required before the installation

2. Find the right Base and Search DN and Server Name

Command output examples which help to evaluate the best DN

3. Command examples

Various command examples dsget|ddsquery and Powershell examples to get the output from chapter 2.

Generic troubleshoot commands for network connection issue.

4. Login to ASSO and configure the integration.

Explains all settings required for the integration and how to set it including User and Groups Filter.

5. Common GUI Errors, Logs and Troubleshooting

The most expected errors displayed in the GUI and logs, for server connection issues.

6. Assistance required by Support?

A brief information for what is required by support to understand the issue and the environment.

1. Prerequisites and Overview

Prerequisites and points to consider before starting with the Integration.

The ASSO integration is implemented by using the ASSO API, authentication is verifiedwith an authentication token on the ASSO server, not via session cookie.

TrueSight integration with ASSO does only support internal User Store and remote User Store with LDAP. No SAML (ADFS) , Kerberos or 2 factor authentication support for remote user stores are supported

It is recommended to install BMC Atrium Single Sign ON Version 9.0.00 Patch 002 or newer, older versions are not recommended.For System Requirements and Installation instructions see the relevant documentation page. https://docs.bmc.com/docs/display/public/sso90/Home

• Installing ASSO

The scope of this document is to integrate ASSO into Windows AD as a Single Sign-On Solution for the TrueSight 10 product family, installing ASSO and generic background details are not covered in this documentation.

Prerequisites before integration

© Copyright 2017 BMC Software, Inc. - BMC Confidential—Internal Use Only

• Service Account in Windows Active DirectoryA service account and password information in Active Directory is required in DistinguishedName format, the product is using this account to connect with simple bind using LDAP or LDAPS protocol to the domain controller, to verify the password and group membership of the login users.

• Access to a Domain Controller

This document provided some commands which are useful to determine the required settings for the integration, to get the command outputs is required if assistance is required by BMC Support for the integration.

• Organize users in groups in Active Directory

The TrueSight products are authorizing users for access and permission according the group member ship in Active Directory, the users should be grouped in Active Directory according the environmental needs.

This task has to be done by a Active Directory Administrator, existing groups can be used. The number of groups depending on the in-house requirements, Users should be grouped according the authorization required by the groups. In most environment 2 - 4 or more different groups are required

Group the Users in Active Directory


• Consider a single group for TrueSight Product Administrators

The Administrators are put usually together in a single groups, since the members have all the same permission.

• Consider different groups according the task permission

Consider different groups for user tasks, at example create a group for users which only have a set or permission, like ViewingReports, open views like Capacity Views in TrueSight Console. Depending on the in-house needs, there might be 2-3 different groups according the needs.

• Consider different groups according the access

Consider different Groups for different access, beside the tasks you can grant access to the object level, like Domains in TrueSight Capacity Optimization or access to certain agents in TrueSight Infrastructure Management. Consider to use different groups to limit access as well.

The connection string for the Domain Controller to connect for authentication, if the ASSO server is in the same subnet and region as other TrueSight products integrated into Active Directory using LDAP, you can reuse this setting if a firewall is allowingcommunication to the host and port.

• LDAP Provider URL

If a product from TrueSight family is integrated into Windows Active Directory, for example TrueSight Capacity Optimization, some of the settings can be used also for the ASSO integration. Since the LDAP integration is different for the TrueSight family products this are examples for TrueSight Capacity Optimization.

Reuse of settings from LDAP integration


• LDAP Context

The root of the LDAP Domain, also called Base DN for example: DC=bmmsup,DC=xy

• Search Account

This is the account used for the initial bind, this account must be in distinguish name format for example:CN=ServiceUser,OU=ServiceAccounts,DC=bmmsup,DC=xy

Other existing settings are not worth to reuse, to find the relevant settings for the ASSO integration follow this document.

The hostname and port of the LDAP Server, only use hostname and port for this setting and no protocol prefix like ldap://

• Primary LDAP Server Name / Port

The most important settings are below, to find the best DN for Search and User Attributes requires some research, the best setting depends on the Active Directory OU structure and the location of the users and groups.

Settings to use in ASSO


• User Account for Search

The Windows Services account used by ASSO. This is the account used for the initial bind, this account must be in DistinguishedName, format for example: CN=ServiceUser,OU=ServiceAccounts,DC=bmmsup,DC=xy, this account can be located anywhere in the AD structure, consider if password changes on AD side, you must synch the password in ASSO.

• DN start to Search and User Attributes

The Base DN to start search is the highest possible organization unit structure under which all users and groups supposed to useASSO are located, the Powershell or dsquery|dsget commands later in the document can be used to evaluate the best settings.

• User Attribute mapping

Use only the sAMAccountName LDAP attribute for mapping, don’t use any other attributes or additional attributes for performance and compatibility reasons. The same Username as for Windows Logins is used.

Base DN and User Search DNIn a typical Active Directory environment users and groups can be located in different organization unit structures. The screenshot right shows the top level of the OU structure.

For example:• CN=Users,DC=BMMSUP,DC=XY ------ Default Users and Groups container

The default Users and Group Container, if all users and groups are located here, this can be used as Base and Search DN.

• OU=TSOM,DC=BMMSUP,DC=XY ----- Organization Unit TSOM

If all users and groups are located in the OU TSOM , this can be used as Base and Search DN.

• OU=TSCO,DC=BMMSUP,DC=XY ------ Organization Unit TSCO

If some users and groups are stored in this OU but also in OU=TSOM, DC=BMMSUP,DC=XY , use DC=BMMSUP,DC=XY as Search and Base DN since this is the DN under which all users and groups can be found

The goal is to find a DN which covers users and groups under beneath, for example DC=BMMSUP,DC=XY is the root of the domain and should find all users and groups. It is recommended to use a DN more down in the OU structure if possible, to avoid performance issues caused by the number of object from LDAP retrieved by the queries.


Additional Base and User Search recommendation

If user login are required from a root DC=BMMSUP,DC=XY

and child domain DC=CHILD,DC=BMMSUP,DC=XY use the root of the domain for Base and Search DN. DC=BMMSUP,DC=XY.

This allows logins all user and groups from root and child domain in the same domain tree.

If user login are required only from a child domain the DN of the child should be used DN as Search and Base DN. Consider in this case to connect to a Domain Controller from the child domain. This approach avoids LDAP queries against a domains not required for login.

For User Logins from Domains in the same Domain forest but with a different domain name, or domains in a remote domain forest with domain trusts, a separate Realm Authentication and Users Stores are required in ASSO for each.


2. Find the right Base and Search DN and Server Name

One of the most important task is to find the best Base and Search DN for performance and security reasons.

It is strongly recommend to work on this before doing the actual ASSO integration starting in the next section 4.

The command examples providing the output are covered in section 3.

To list all users which are a member of the group in distinguished format, useful to determine the organization unit which contains the required users. Replace TSCO with the name of the command.

List of users in a group – Example 1


This is an expected output example:distinguishedName name SamAccountName----------------- ---- --------------CN=qpasa,CN=Users,DC=bmmsup,DC=xy qpasa qpasaCN=Stefan Antelmann,OU=BMM,DC=bmmsup,DC=xy Stefan Antelmann santelmaCN=Anajali Chauhan,OU=TSCO,DC=bmmsup,DC=xy Anajali Chauhan achauhanCN=Giorgio Gasparini,OU=TSCO,DC=bmmsup,DC=xy Giorgio Gasparini ggaspariniCN=Vishal Kshirsagar,OU=TSCO,DC=bmmsup,DC=xy Vishal Kshirsagar vkshirsCN=Kevin Joyce,OU=TSCO,DC=bmmsup,DC=xy Kevin Joyce kjoyceCN=Snehal Patil,OU=TSCO,DC=bmmsup,DC=xy Snehal Patil spatil

All users expect the first 2 are located in OU=TSCO,DC=bmmsup,DC=xy, if the first 2 users require no login in ASSO the DN OU=TSCO,DC=bmmsup,DC=xy can be used, if all users need to login the DN DC=bmmsup,DC=xy must be used for the Base and Search DN. LDAP searches work only working recursively the structure down, consider to read a DN from right to left, left is the root.There difference for the name attribute for some users, this is in fact the common name of the User DN. In some AD environments it is the same as the sAMAccountName in some it is used for Full Name, this difference are not an issue because the ASSO integration is using the sAMAccountName.

Another example , where all users are located in the same Organization Unit, replace TSCO in the command example below with the name of the group.



distinguishedName name SamAccountName----------------- ---- --------------CN=qpasa,OU=TSCO,DC=bmmsup,DC=xy qpasa qpasaCN=Stefan Antelmann,OU=TSCO,DC=bmmsup,DC=xy Stefan Antelmann santelmaCN=Anajali Chauhan,OU=TSCO,DC=bmmsup,DC=xy Anajali Chauhan achauhanCN=Giorgio Gasparini,OU=TSCO,DC=bmmsup,DC=xy Giorgio Gasparini ggaspariniCN=Vishal Kshirsagar,OU=TSCO,DC=bmmsup,DC=xy Vishal Kshirsagar vkshirsCN=Kevin Joyce,OU=TSCO,DC=bmmsup,DC=xy Kevin Joyce kjoyceCN=Snehal Patil,OU=TSCO,DC=bmmsup,DC=xy Snehal Patil spatil

All users are located in OU=TSCO,DC=bmmsup,DC=xy, if all users and groups are stored in the a single OU you can use this as the Search Base DN.

Another example with a different OU structure.



distinguishedName name SamAccountName----------------- ---- --------------CN=qpasa,OU=EMEA,OU=TSCO,DC=bmmsup,DC=xy qpasa qpasaCN=Stefan Antelmann,OU=EMEA,OU=TSCO,DC=bmmsup,DC=xy Stefan Antelmann santelmaCN=Anajali Chauhan,OU=APAC,OU=TSCO,DC=bmmsup,DC=xy Anjali Chauhan achauhanCN=Giorgio Gasparini,OU=EMEA,OU=TSCO,DC=bmmsup,DC=xy Giorgio Gasparini ggaspariniCN=Vishal Kshirsagar,OU=APAC,OU=TSCO,DC=bmmsup,DC=xy Vishal Kshirsagar vkshirsCN=Kevin Joyce,OU=US,OU=TSCO,DC=bmmsup,DC=xy Kevin Joyce kjoyceCN=Snehal Patil,OU=APAC,OU=TSCO,DC=bmmsup,DC=xy Snehal Patil spatil

Users are separated further down to regional location. ,OU=EMEA,OU=TSCO,DC=bmmsup,DC=xy and,OU=US,OU=TSCO,DC=bmmsup,DC=xy and ,OU=APAC,OU=TSCO,DC=bmmsup,DC=xyIf all users require login the Base and Search DN can be OU=TSCO,DC=bmmsup,DC=xy, however if only users APAC region are supposed to login OU=APAC,OU=TSCO,DC=bmmsup,DC=xy should be used.

The groups must be located also under the Base and Search DN, this command example shows the DN of the group TSCO for verification. It is also useful to set up Group Filter in ASSO to display only groups and users which are members of the filter, this avoids the display of groups and users which don’t require ASSO access but can be found in the same Organization Unix structure.

Details of a group – Example 1


DistinguishedName Name GroupCategory GroupScope----------------- ---- ------------- ----------CN=TSCO,OU=TSCO,DC=bmmsup,DC=xy TSCO Security Global

If all users are located under this DN structure along with the group, OU=TSCO,DC=bmmsup,DC=xy can be used as the search Base DN. if users are located in a different structure consider this, a Base and Search DN most down from the root of the domain is recommended.For example in GetADGroupMember Example 1, users are located in different independent structures like OU=BMM,DC=bmmsup,DC=xy . Therefore Base and Search DN has to be set to DC=bmmsup,DC=xy because all users can be found under this DN

A command example which show details for a single user without a group scope, this command shows also if the account is enabled or locked out due to many invalid login attempts.

Details of a User – Example 1


Description :Name : qpasaDistinguishedName : CN=qpasa,CN=Users,DC=bmmsup,DC=xyDisplayName : qpasaEnabled : TrueSamAccountName : qpasaLockedOut : False

This command can be used also to verify the Distinguished Name of the ASSO Service account used as “User for Search”, to verify the correct DN and if the account is enabled or locked out.

3. Command examples

The Get-ADGroupMember, Get-ADGroup and GetADUser examples are Powershell cmd-let and therefore the need to run the commands from Powershell. In some environments before Windows 2012 the required modules might not be installed and causing errors, please use the dsquery|dsget examples if you see errors that the “term” could not be found .

If assistance is required by a BMC TSA the most important is the Active Directory Structure. To see this structure a output of the Powershell cmd-let commands or dsquery|dsget commands is required.

The Powershell cmd-let and dsquery|dsget commands need to be run on a Domain Controller or on a box with RSAT Installed.

If there are any errors with the commands when using copy and paste, please check the double quotes and hyphen in the command examples. Some PDF Viewer change those from ASCI to typographical characters which can cause issues in the command line cause that the command does not work.

Powershell cmd-let not available

The following kind of error is displayed if the Powershell

cmd-lets are not installed.

Please use the dsquery | dsgetcommand examples if you encounter an error like this.


List all users which are a member of the group in DistinguishedName format, useful to determine the highest possible organization unit structure. The group name used to query in this example is TSCO.

Get-ADGroupMember


Get-ADGroupMember TSCO | Format-Table -Property distinguishedName,name,SamAccountName -Autosize | Out-String -Width 4096

distinguishedName name sAMAccountName----------------- ---- --------------CN=qpasa,CN=Users,DC=bmmsup,DC=xy qpasa qpasaCN=Stefan Antelmann,OU=BMM,DC=bmmsup,DC=xy Stefan Antelmann santelmaCN=Anajali Chauhan,OU=TSCO,DC=bmmsup,DC=xy Anajali Chauhan achauhanCN=Giorgio Gasparini,OU=TSCO,DC=bmmsup,DC=xy Giorgio Gasparini ggaspariniCN=Vishal Kshirsagar,OU=TSCO,DC=bmmsup,DC=xy Vishal Kshirsagar vkshirsCN=Kevin Joyce,OU=TSCO,DC=bmmsup,DC=xy Kevin Joyce kjoyceCN=Snehal Patil,OU=TSCO,DC=bmmsup,DC=xy Snehal Patil spatil

This output is required for every Windows AD Group supposed to use in ASSO, this output does help to understand the Base and Search DN and shows if the Users are expected in the related groups.

What you see from the output under name is the common name attribute, which is not used by ASSO. However what you see under sAMAccount name is the User name used for Logins in the TrueSight products.

If the Get-ADGroupMember Powershell cmd-let is not available or working for whatever reason the dsquery and dsget commands can be used, again replace TSCO with the group name in Active Directory

Get-ADGroupMember not available


dsquery group -name TSCO | dsget group -members -expand

"CN=csala,OU=TSCO,DC=bmmsup,DC=xy""CN=Snehal Patil,OU=TSCO,DC=bmmsup,DC=xy""CN=Kevin Joyce,OU=TSCO,DC=bmmsup,DC=xy""CN=Narayan Prasad,OU=TSCO,DC=bmmsup,DC=xy""CN=Vishal Kshirsagar,OU=TSCO,DC=bmmsup,DC=xy""CN=Giorgio Gasparini,OU=TSCO,DC=bmmsup,DC=xy""CN=Anajali Chauhan,OU=TSCO,DC=bmmsup,DC=xy""CN=Stefan Antelmann,OU=BMM,DC=bmmsup,DC=xy""CN=qpasa,CN=Users,DC=bmmsup,DC=xy"

The output does only show the Distinguished User attribute, but this is the main purpose of this command.

Same as for the Powershell script, the commands need to be run on a Domain Controller or on a box with Windows RSAT tools installed.

Useful to set up Group and Users Filter in ASSO to display only groups and users which are members of the filtered groups, to avoid the display of groups under the Base and Search DN which don’t require ASSO access.

Get-ADGroup


Get-ADGroup TSCO | Format-Table -Property DistinguishedName,SAMAccountName,GroupCategory,GroupScope -Autosize

DistinguishedName sAMAccountName GroupCategory GroupScope----------------- ---- ------------- ----------CN=TSCO,OU=TSCO,DC=bmmsup,DC=xy TSCO Security Global

The DistinguishedName is required for the Users Filter.The sAMAccountName attribute can be used for the Group FiltersThe GroupScope, no matter if Global or Local, if Universal consider to connect to a Global CatalogGroupCategory, Security is required, you cannot use distribution groups as used far mail.

The dsquery and dsget command if the Get-ADGroup Powershell cmdlet is not working. The output is quite similar as with Get-ADGroup

Get-ADGroup not available


dsquery group -name TSCO | dsget group -dn -samid -scope

dn samid scope secgrpCN=TSCO,OU=TSCO,DC=bmmsup,DC=xy TSCO global yes

The dn = DistinguishedName is required for the Users Filter.The samid = sAMAccountName attribute is required for the Group FiltersThe scope = GroupScope, no matter if Global or Local, if Universal consider to connect to a Global CatalogThe secgrp = GroupCategory , Security is required, you cannot use distribution groups as used for mail.

Powershell command example to show details for a single user without a group scope since a user can be a member of many groups, this command shows also if the account is enabled or locked out.

Replace the string qpasa with the sAMAccountName of the user.

Get-ADUser


Get-ADUser qpasa -Properties * | select -Property Description,Name,DistinguishedName,DisplayName,Enabled,SamAccountName,LockedOut

Description :Name : qpasaDistinguishedName : CN=qpasa,CN=Users,DC=bmmsup,DC=xyDisplayName : qpasaEnabled : TrueSamAccountName : qpasaLockedOut : False

This command can be used also to verify the Distinguished Name of the ASSO Service account used by ASSO as “User for Search” and to verify if the account is enabled or locked out due to too many invalid login attempts.

Command example which show details for a single user without a group scope since a user can be a member of many groups, this command shows also if the account is enabled or locked out.

Replace the string qpasa with the sAMAccountName of the users.

Get-ADUser not available


dsquery user -samid qpasa | dsget user -fn -n -samid -disabled

dn samid fn disabledCN=qpasa,CN=Users,DC=bmmsup,DC=xy qpasa qpasa no

It provides a similar output as Get-ADUser Powershell cmd-let, the format is different. Not the lockout information though.

Command can be useful if a single user is missing, instead of using the Get-ADGroupMember cmdlet or the related dsget|dsquery common. The output should list all groups in DN Format. Consider that a user can me a member of many groups, so the output can become quite large, the command may run long and can become truncated regardless what format options are used.

Get the groups from a single user


Powershell example, without additional formatting as for the other examples, replace qpasa with the sAMACoountName of the user

Get-ADUser qpasa -Properties MemberOf | Select -ExpandProperty memberof

CN=TSCO,CN=TSCO,OU=TSCO,DC=bmmsup,DC=xyCN=Domain Users,CN=Users,DC=bmmsup,DC=xy

dsquery | dsget example, replace qpasa with the sAMACoountName of the user

dsquery user -samid qpasa | dsget user -memberof -expand

CN=TSCO,CN=TSCO,OU=TSCO,DC=bmmsup,DC=xyCN=Domain Users,CN=Users,DC=bmmsup,DC=xy

In a typical AD environment all Domain Controller are registered in DNS with appropriate SRV records, the following nslookup commands can be used to verify the LDAP Server from DNS.

The example output is from Windows, but the same command can be used on Linux, please replace bmmsup.xy with the DNS name of the domain to connect.

Verify LDAP Server Name by using DNS


nslookup -type=srv _ldap._tcp.bmmsup.xyServer: bmmsupb1.bmmsup.xyAddress: 10.0.0.1

_ldap._tcp.bmmsup.xy SRV service location:priority = 0weight = 100port = 389svr hostname = dc1.bmmsup.xy


dc1.bmmsup.xy internet address = 10.0.0.1dc2.bmmsup.xy internet address = 10.0.0.2

If you consider to use a global catalog for the connect, because user login are required for root and child domainsYou can use this command, either there is only one DC a global catalog, or every DC is a global catalog.

The example output is from Windows, but the same command can be used on Linux, please replace bmmsup.xy with the DNS name of the domain to connect.

Check for Global Catalogs by using DNS


nslookup -type=srv _gc._tcp.bmmsup.xyServer: bmmsupb1.bmmsup.xyAddress: 10.0.0.1



dc1.bmmsup.xy internet address = 10.0.0.1dc2.bmmsup.xy internet address = 10.0.0.2

If ASSO has problems to connect to the LDAP server this commands can be used to determine connect issues.

Check for LDAP Server Name connection issues


• ping the hostname with ping command used in LDAP Provider URL attribute and verify if the IP is correct

> ping dc1.domain.com

PING hostname.domain.com (10.0.0.1) 56(84) bytes of data.

64 bytes from hostname.domain.com (10.0.0.1): icmp_seq=1 ttl=64 time=0.040 ms

• Use telnet command if available

> telnet hostname.domain.com 389

Trying 10.0.0.1...

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 connection refused error ( Firewall or no LDAP available) or Unknown host for wrong hostname on unsuccessful connect.

4. Login to ASSO and configure the integration

Once evaluated the best Base and Search DN you can start with the integration.

After the successful integration you should see the Users and Groups from Windows AD in ASSO on the Users and Groups Tab.

The next pages cover configuration with ASSO against the root of the Domain, this is easy to get integrated. But BMC recommends to use a DN which is far as possible away from the root of the Domain but has all users and groups under beneath required to login.

First login to ASSOThe default Administrator name is amadmin, the password was given when installing the product, please note the password, this account is required for maintenance if ASSO cannot connect to a LDAP Server.

As non ASSO administrator, meaning a simple Windows AD user available on the Users tab is not allowed to login to ASSO.

Open the BMCRealm used for the integration, by click on in on the BMCRealm name .


Realm EditorIn the Realm Editor it is required to create a new Realm Authentication and a User Stores

1. Create a new Realm Authentication, by using the Add Button in Green, after completing this configuration

2. Create a new User Stores, by using the Add Button marked as red, once the Realm Authentication was saved.

Don’t delete the Internal LDAP Realm Authentication or embedded User store, without this a login as the local amadmin user is not possible and maintenance may fail if the Windows Domain Controller cannot confirm a authentication.


Realm Authentication

Realm Authentication Type

After using the Add Button to add a new Realm Authentication select the type LDAP / Active Directory from top of this list.

This type is using a simple LDAP bind against the Windows Active Directory.

Other types are not covered in this documentation.


LDAP / Active Directory Editor – General Name: The Full Qualified Name of the LDAP Server to connect, don’t use the hostname only, please use the full qualified name with the DNS domain postfix.

Port: If the Active Directory supports LDAPS, make sure that you use 636 Port and select Use SSL. The Import SSL Certificate does import the Certificate from the Domain Controller and stores it in the ASSO Truststore, this requires a service restart. If the certificate is renewed per default every 90 days on the domain controller, the import of the certificate must be done again by using the checkbox. If the Active Directory does not support LDAPS, use Port 389 and unselect the Use SSL box.

User Account for Search:

The user account in distinguished format, if the password of that user does change the password has to be changed in ASSO also.

Base DN: In the given examples users and groups are stored in different OU under the domain root. OU=TSCO,CN=BUMMSUP,DC=XY

and OU=BMM,CN=BUMMSUP,DC=XY therefore the root of the domain has to be used.

Attribute for User Profile Name: type the string sAMAccountName

Attributes for User Search: type the string sAMAccountName to the Attribute Name field and don’t forget click on Add.


LDAP / Active Directory Editor – Advanced Name: A secondary LDAP Sever can be specified here for HA purposes if the primary server is not available for maintenance.

Port: More details for the port.

You can Use SSL only if you Domain Controller support LDAPS on Port 636, this is not enabled by default in a Windows Active Directory and requires a Certificate Authority for the SSL certificates. If unsure that LDAPS is available please verify this with a in-house with an Active Directory Administrator.

If no LDAPS on port 636 is available, use LDAP using Port 389.

Don’t mess up with the Ports, if the Use SSL feature is enabled the Port has to be set to 636, it won’t work with Port 389 and the other way around.

Global Catalog:

For large environment with multi child domains, or if Universal Groups are used across Windows Active Directory sites, a connect to a Global Catalog can be considered for performance reasons. If unsure verify this topic with the in-house Domain Administrator which has an picture of the Windows Forests. The Ports to connect to a Global Catalog is LDAP Port 3268 and LDAPS 3269


User Stores

Realm Authentication:

Set the Flag to Sufficient as marked in red, if it is set to required login may not work in intermitting network issues to the Domain Controller, ASSO is caching the session for some while.

User Stores:

Use the Add button and select LDAPv3 User Store.


LDAPv3 User Store Editor – GeneralAlmost the same settings has to be used as for the LDAP / Active Directory Editor – General Tab.

Set a Name for the Users Store in the example it is WindowsAD.

LDAP Server Name , Port and User Account for Search settings are the same and should be in synch.

The External Attribute as marked in red has to be set to sAMAccountName please enter this string and use the Add Button

Don’t add any user Attribute Mapping for performance reasons and compatibility with TrueSight 10.

With this configuration ASSO shows the samAccountName in AD as the User ID in the Users and Groups Tab, additionally it shows the First Name and Last Name attributes from AD.


LDAPv3 User Store Editor – SearchNot many changes required in the User Store Editor Search Tab.

Set again the Search Base DN as on Active Directory Editor General Tab.

Under Users Search Attribute it is required to change the setting from cn to sAMAccountName, this is required for the TrueSight products.

Untick the People Container, this does only work if all users are in the same Organization Unit to which you set it. It could become useful if the groups are stored in a different organization structure. For example if groups are stored in OU structure CN=User,DC=BMMSUP,DC=XY, but users are stored in OU=TSCO,DC=BMSUP,DC=XY. For Search and Base DN you have to use DC=BMSUP,DC=XY, but you can limit Users to OU=TSCO with the Enable Container Attribute.

Save changes, no other changes are required, the Groups Search Filter could be used to display only the required groups discussed later.


ASSO Users TabWith the correct settings, ASSO is showing the AD Users on the Users Tab. All Accounts which are found under the Base /Search DN are listed.

In the right upper Corner you can use the Filter, replace * with a string of the account you are looking for to Filter out the users, verify that you find the account you search in this View.

The search against Active Directory is limited to 1000 results, don’t expect a higher number here, if you miss your account but see a higher number of results it might be that you reached the limit.

To show the Accounts only for some active Directory Groups check the next 2 slides.


ASSO Groups TabWith the correct settings, ASSO is showing all AD Groups from Active Directory which can be found under the Base and Search DN, which are more as required

It does list also internal Groups in the from the embedded User store. Capacity_ Administration and Capacity_View used by TrueSight products . As a ASSO Administrator you can add Users and Group from Active Directory into a internal Group.

If you use the Add Button on Groups Tab, this will create the Group in the embedded ASSO Users Store, but not in Active Directory.

To show only a set of groups check the next slide.


Groups /Users FilterTo only shows Users and Groups from specific AD Groups in ASSO you can set User and Group Search Filter in the LDAPv3 Editor.

The Users filter has to be set to use the DistinguishName of the Active Directory group.

The Groups Filter is requires the sAMAccountName of the Active Directory Group.

The this setting use the Get-ADGroupexamples on the next slides.


The filter on Users with the groups, it is required to use the distinguished name of the group, for example 2 groups are in our interest with the name BMM and TSCO.

Users Filter


Get-ADGroup TSCO | Format-Table -Property DistinguishedName,Name,GroupCategory,GroupScope -Autosize


Get-ADGroup BMM| Format-Table -Property DistinguishedName,Name,GroupCategory,GroupScope -Autosize

DistinguishedName Name GroupCategory GroupScope----------------- ---- ------------- ----------CN=BMM,OU=BMM,DC=bmmsup,DC=xy TSCO Security Global

The filter is this example: (&(objectCategory=person)(objectclass=user)(|(memberOf="DNY")(memberOf="DNX")))Replace “DNY” and “DNX” with the DN of the groups, you can filter out even more groups if required

(&(objectCategory=person)(objectclass=user)(|(memberOf=CN=TSCO,OU=TSCO,DC=bmmsup,DC=xy)(memberOf=CN=BMM,OU=BMM,DC=bmmsup,DC=xy)))

It is recommended to build the filter right above in a text file, to avoid lines or white spaces in this string, the line has to be a single line.

The filter on Users with the groups, it is required to use the distinguished name of the group, for example 2 groups are in our interest with the name BMM and TSCO

Group Filter


Get-ADGroup TSCO | Format-Table -Property DistinguishedName,Name,GroupCategory,GroupScope -Autosize


Get-ADGroup BMM| Format-Table -Property DistinguishedName,Name,GroupCategory,GroupScope -Autosize

DistinguishedName Name GroupCategory GroupScope----------------- ---- ------------- ----------CN=BMM,OU=BMM,DC=bmmsup,DC=xy TSCO Security Global

The filter is this example: (&(objectclass=group)(|(sAMAccountName=“G1”)(sAMAccountName=“G2)))Replace “G1” and “G2” with the sAMAccountName of the groups, you can filter out even more groups if required

(&(objectclass=group)(|(sAMAccountName=TSCO)(sAMAccountName=BMM)))

It is recommended to build the filter right above in a text file, to avoid lines or white spaces in this string, the line has to be a single line.

Users Filtered

After setting the Filter for Users, the ASSO Console does show on the Users tab only the Users of the Groups you set the filter for in Active Directory. Before it was showing all Users under the configured OU structure.

When using a Active Directory User Store to create Users in the embedded Users Store is not possible. Users has to be created in Active Directory.

Now with Users filtered out, by the groups the number of users is reduced from 89 to 23, in a large Windows AD environment you may get 1000 Users displayed without the Filter.


Groups FilteredWithout the filter the ASSO Console was displaying 192 groups now it is reduced to 19.

The User and Group Tab does not show only the Users in Active Directory, it displays also the preexisting groups exist in the embedded Users Store. So don’t wonder if you see more groups as supposed.

From this page only the Groups TSCO, TSCOLE and BMM are Active Directory Groups.

You can create new groups in ASSO and add Users or Groups you see in ASSO console to the groups, this can be useful if only a few Groups are existing in Active Directory but more permission granularity is required in the TrueSight products. However this layers responsiveness to the ASSO Administrator, and may not apply to company in-house security policy.


FinalizeLast Configuration Requirements

Change the User Profile to Ignored

Set the Flag for all Realm Authentication to Sufficient.

If you see all Users and Groups on the ASSO Tabs and you use for Attribute Mapping only the sAMAccountName the configuration is complete and you can start to integrated the TrueSight Products into ASSO.

Further information which can help to troubleshoot the integration can be found in the next sections


5. Common GUI Errors, Logs and Troubleshooting

When saving the changes for a Realm Authentication or for the Users Store the ASSO Console shows errors when saving the changes and if the ASSO cannot connect to the Domain Controller or the Search Account cannot bind to the LDAP.

Invalid configuration settings on the Base DN, Search DN, with the LDAP attribute mapping and on Users and Group Filters are not generating an error, this will only result that you are not see what you are expected to see on the Users and Groups Tab.

BMCSSG1827WUnable to bind to LDAP Server

This means that the LDAP Server is available, and ASSO can connect to the configured port but ASSO cannot bind with the configured account.

There is a conflict in the User Account for Search setting. Please check for typos in the User DN, please check if the correct Password is used. To check the DN of the User use the Get-ADUser example from Command Example section 4, or use the alternate dsquery|dsget example.

Consider if the wrong password was tried in multiples times, that the account may got locked out.


BMCSSG1822WCould not connect to remote server on specific port.

This error says that the LDAP Server is available, but there is nothing listen on the port.

Only use Port 389 for LDAP and 636 for LDAPS, for a Global Catalog it is LDAP Port 3268 and LDAPS 3269.

The screenshot shows a wrong port.

If the correct Ports are used, please check for Firewall blocking the communication, and check if the box is hosting is a Domain Controller, and has the Global Catalog enabled if used.


BMCSSG1832WInvalid Hostname specified.

This error means that ASSO cannot connect to the Domain Controller.

It means that the Server Name does not exists and or is not registered in DNS.

Please try to ping the hostname you can use also the nslookup example in the Command Example Section 4 to verify if the host if the hostname is registered in DNS as a Domain Controller.


LDAP / LDAPS MixupUnable to bind to LDAP Server

The screenshot reveals a typical port and protocol conflict, Use SSL is enabled, but the connection is against the non SSL LDAP Port. If the Domain Controllers support LDAPS use Port 636, if not unselect the Use SSL Option and use Port 389.

The same message does appear when Use SSL is not selected but you connect to the LDAPS 636 port.


ASSO Logs - Troubleshooting


The Atrium Single Sing-On Documentation is the best source to get more details about the log.

Atrium SSO - Collection Diagnostic ( Logs )

The documentation gives some details of basic troubleshooting.

Atrium SSO Troubleshooting

However the information in this document does cover more details to troubleshoot issues with the external LDAP integration and Active Directory.

https://docs.bmc.com/docs/display/public/sso90/Log+file+locations

https://docs.bmc.com/docs/display/public/sso90/Log+file+locations

https://docs.bmc.com/docs/display/public/sso90/Troubleshooting

6. Assistance required by Support?

BMC Support can assist with the integration but requires a understanding of the Windows Domain Structure.

To get the integration done as quick possible to provide the information summarized on the next slide.

Core steps for ASSO integration


• Errors in ASSO when saving the changes

The error is most likely pointing to an issue with the Domain Controller to connect, verify that the box is reachable and the correct port 389/636 vs. LDAP/LDAPS. Verify that the services account is working, check the DN of the “User Account for Search” with Powershell cmd-let Get-ADUser ( Page 39, or dsquery|dsget command at Page 40.

• Missing Users and Groups in ASSO

If a Base DN and Search DN is used which is not pointing to the root of the Domain, try it with the domain root first e.g. DC=BUMMSP,DC=XY. Remove existing Users and Group Search Filter from Users Store if modified and use the default. This may list all users from the domain but confirm that it is working. Please filter out for groups or users manually in the console ( Page 25 ) to verify if the missing group or user is listed. To really understand why users or groups are missing, it is required to have a understanding for domain organization structure. Provide the outputs from Get-ADGroupMember Powershell cmdlet against the groups supposed to use ASSO ( Page 35) or dsquery|dsget command ( Page 36 ). If a single User is missing or cannot use ASSO send the output of the Powershell cmdlet Get-ADUser ( Page 40 ) or dsquery|dsget command example ( Page 41 ). The information in which groups the user is a member of on Page 41, could be also useful.

Please spend some time to explain what you see when you have problems with the migration. Do you miss some Users or Groups from the Tabs or all? Do the users belong to a different AD Group? Or do you get an error when you save changes in ASSO? Details about the issue are appreciated for better understanding.

Information required by Support


• Provide outputs from Powershell or dsquery|dsget commands outputs from all Groups supposed to login. Provide Powershell output or dsquery|dsget from a missing user, this user might be not in the groups as expected.

• Provide Screenshots from the configuration showing the 2 Tabs from the Real Authentication and Users Stores, if parameters are truncated in the screenshot (most likely the Group Filter and Users Filter or Account DN used for Search) provide this information also a Text.

• Please zip and send us the logs from the AtriumSSO\tomcat\logs ( Windows) or AtriumSSO/tomcat/logs ( Linux)

• The most important information required by support is the output of the Powershell commands and settings used in the product if you miss some Users or Groups. If the DistinguishedName information from the Users is considered as sensitive the Users , or the OUs can be renamed as long as the structure is in synch, support needs to understand the structure and suggestions can made on the structure.

Thank You


About BMC

BMC, BMC Software, the BMC logo, and the BMC Software logo, and all other BMC Software product and service names are owned by BMC Software, Inc. and are registered or pending registration in the US Patent and Trademark Office or in the trademark offices of other countries. All other trademarks belong to their respective companies. © Copyright 2017 BMC Software, Inc.

BMC – Bring IT to Life BMC digital IT transforms 82% of the Fortune 500.

BMC is a global leader in innovative software solutions that enable businesses to transform into digital for the ultimate competitive advantage. Our Digital Enterprise Management solutions are designed to fast track digital business from

mainframe to mobile to cloud and beyond

http://www.bmc.com/legal/trademarks-third-party-attributions.html

Documents

ASSO integration in Windows Active Directory for …...If a product from TrueSight family is integrated into Windows Active Directory, for example TrueSight Capacity Optimization,