One of the authentication Methods for Remedy Single Sign-On is LDAP. LDAP (Lightweight Directory Access Protocol) is an application protocol to manage and access distributed directory information services over a network. For a high level look at what the LDAP protocol is see whatisLDAP.pptx attached.
There are many different implementations of LDAP servers the most common are Open Ldap, Apche DS, OpenDJ, but by far the most popular is Microsoft Active Directory.
LDAP is deployed to the requirements of the organisation, this is why you are very unlikely to find two LDAP system configured in exactly the same way.
In this post we are going to take a look at how to configure Active Directory with Remedy Sigle Sign-On, and will use True Sight as the application example, but the configurations will also be valid for other BMC applications like AR server, MyIT, BAO and ADDM.
Getting to know your LDAP
If you are not the LDAP administrator then its quite difficult to know how to configure searches against your LDAP server. By far the easiest and quickest way to get the information required to configure LDAP with RSSO is to speak to the LDAP administrator regarding which searches should be used for the information you want, but as so often the case the LDAP admin might not be available to answer your questions quickly.
In the following sections we'll take a look at the information you need to be able to configure LDAP with RSSO.
Need to know
A list of things we need to know before being able to configure LDAP Authentication in RSSO
- LDAP server name or farm name if in a HA/LB environment
- Port - Server port default 389 & 636 for SSL connection (if SSL you will need to add the LDAP server certificate to the RSSO keystore)
- BIND DN - The user name you will use to connect to the LDAP server
- BIND Password - The password for the BIN DN user
- Users Base DN - Used to indicate from where searches for users and groups starts from. Some LDAP servers contain tens of thousands users, so the more specific you can make this the better to limit searching the whole DS structure
- User Search Filter
- Identity Attribute
- Users Group Filter
- Group Name Attribute
- Group Search Filter
The LDAP browsers should allow you to view only (readonly) changes to the LDAP server itself should not be allowed unless you are an LDAP Administrator.
In this post we will work with LDAPAdmin but you can do the same things with other LDAP browsers.
Connecting to the LDAP Server (LDAP Admin)
- Open LDAPAdmin --->Start-->Connect--->Create New Connection
- Give a connection name (any descriptive name)
- In the "Host" field enter the name of the LDAP server
- Port 389 is the default LDAP port, if the LDAP server is using SSL Select the SSL box, the port number will change to default SSL port 636 (you will be shown a message for certificate trust later on in the process)
- Uncheck the "Anonymous Connection" In the user account section
- In the "User Name" field, depending on how your LDAP server is configured you can either just use a username or an ldap bind user format name. If you are using active directory the format will be something like "CN=myusername,DC=mydomain,DC=com" If you login to Active directory domain you should be able to use your AD Domain account (assuming you have been permission) Eitherway the quickest and fastest way to find this information out is to speak to your LDAP admin
- In the "password field" enter the password for the user
- Click the "Test Connection" button
If the connection was successful you will get a "Connection Successful" at this point click "Fetch DNs" button and you will be presented with a list of DNs in the LDAP server. Select the first one in the list. If you are using SSL you will get a message indicating if you want to trust the certificate click "Yes"
9. Click "OK" to save
If the test connection failed with messages containing
- Exception Security Context - The username or password is incorrect
- LDAP Server Down - Either the host name is incorrect or you are not able to ping the LDAP server from your location
With both of these failures above, you will need to speak to your LDAP Administrator
At this point you should have Five of the need to know values for configuring LDAP with RSSO
- LDAP Server name
- BIND DN
- BIND Password
- Users Base DN
Values Used in the following Example
User: Jose Mourina - We are going to use this user to login to our end application (TSOM)
Base DN: SSO.BMC.COM - Our Search Base, where we will start searching
After you open the new connection you will see the LDAP hierarchy (fig1) This will show the top level of the Directory Service
The next thing we need to do is find where our users are in the Directory Service (DS) In this example its quite obvious the users are likely to be under CN=Users. Some LDAP DS
are huge and where the users you are looking for is not always obvious straightaway, so we'll do a search to find the user. We need to know at least one of the usernames in the system
so we can do our search.
1. Right Click on the top level entry in this case "DC=SSO,DC=BMC,DC=COM" and select "search"
2. At this point we DO NOT want to click the search button as that will search the whole DS and that might take a while depending on how large the DS is
3. If you know the use name or email address of one of the users enter it in the appropriate field and click "start" If that user is in the system it will be listed in the results pane
4. We can also do a custom search (this is what RSSO will also use to search for the users) Click the "Custom" tab and enter the filter
(&(objectCategory=user)(cn=Jose Mourina)) Here we are using sAMAccountName the default user attribute for active directory, other LDAPs may userID or UID as the
user attribute. Click "start" to start the search
If you don't know what the user attribute is or a particular user name, then you will have to manually expand the TopLevel hierarchy to find a user name, from there you will be able to find the information needed
Here we've searched for a user called "Jose Mourina" (fig2) Right Click select "Go to" and close the search window
We now see the user attributes for the user "Jose Mourina" From here we can see the following attributes for this user
- objectClass: user/person
- cn: Jose Mourina
- memberOf: CN=Operators,CN=Users,DC=SSO,DC=BMC,DC=COM
- sAMAccountName: JOSE01 (For Active directory this is the default userID attribute, for other LDAP systems it usually is UID or UserID) The attribute value needs to be unique
- objectCategory: CN=Person,CN=Schema,CN=Configuration,DC=SSO,DC=BMC,DC=COM
- distinguishedName: CN=Users,DC=SSO,DC=BMC,DC=COM (for the user search base)
The user is part of the "Operators" group. We can find where in the DS the group is and get the group attribute by right clicking on the "MemberOf" attribute and select "Go to" This will bring us to the group details (fig3)
We can see our group attributes are (fig3)
- cn: Operators
- objectClass: group
- distinguishedName: CN=Operators,CN=Users,DC=SSO,DC=BMC,DC=COM (which will become out group search Base DN)
- objectCategory: CN=Group,CN=Schema,CN=Configuration,DC=SSO,DC=BMC,DC=COM
We now have all the information we need to configure LDAP authentication with RSSO. This is a simple users and group setup, we will take a look a users who belong in different groups and nested groups later on.
External & RSSO Attributes mappings
The tables below show the LDAP attributes (External) and how they are mapped to the fields in the RSSO console & the values used in this example
User Attributes (User Authentication tab)
Group Attributes (Group Support tab)
Configuring LDAP Authentication in RSSO Admin console
Out of the box install of RSSO you should only have the "Local Authentication" configuration. Click on "Enable chaining" --> "Add Authentication"
1. Click on the "Preset" dropdown box and select "Active Directory" This will fill the user search and group search fields with the most common configuration (we will change them later)
- Enter the server host name in the "Server Host" field
- Enter the port number (if you are using secure connection check the TLS check box, you would be required to already add the certificate to the server keystore)
- Enter the BIND DN user in the "BindDN" field
- Enter the users search base in the "Users Base DN" field
5. Check the "Enable Group retrieval" check box, since we need the groups retrieved for true sight later on
At this point Click on the "Test" button to check the connection to the LDAP server, if it shows "LDAP Connection Successful" Save the configuration (fig 5)
If the connection fails and you are using the same connection configuration as in the LDAP browser then check to see if you can ping the LDAP server from the RSSO server, and ports ar e not blocked on the RSSO server side.
Authentication vs Authorization
The Authentication and Authorisation of users are done at different stages of the login process. RSSO's main function is to do the Authentication, either with it's internal user store or an external Identity provider (IDP) like LDAP, ADFS & Kerberos. Once Authentication is done successfully a token is created in the RSSO database (IssuedTokens table) for that user, this token will be used to track the user session throughout it's life span (until the user logs out of the last application). RSSO then sends the userID and groups to the calling application, where the application will do the Authorisation and give the user the correct permissions identified by the groups RSSO sent along with the userID. The application will use it's internal logic to decide what the user is able to access.
One rule of thumb to remember is, if you can see the user's ID in the RSSO console's sessions list then the Authentication part has been done successfully.
User Authentication Tab
The preset for Active Directory preset on the User Authentication Tab is:
User Search Filter *: (&(objectCategory=user)(sAMAccountName=$USER$)) you should be able to run this filter straight in the LDAP browser's search function, you will need change $USER$ parameter to a specific userID and run the search from the base DN that was put in the "User Base DN" field, for example (&(objectCategory=user)(sAMAccountName=jose01)) will bring back the user details for user Jose Mourina. The $USER$ parameter is an internal RSSO parameter to determine the User's USERID and should always in the "User search Filter "field
Identity Attribute *: Is the user attribute for user's in Active Directory the default is sAMAccountName, other popular attribute names are UID & UserID (this will be set on the LDAP server itself and is not configured in RSSO)
Get All Users Filter (optional): This field is used to search all users in the DS under the Base Search given. This field is optional. The recommendation here is not to actually use it unless
the Base Search DN is very specific. Running this filter search will bring back all users, and can potentially do a long search on the DS. For example if this filter was ran in an LDAP browser at the top of the DS then it could potentially return tens of thousands users. Unless sure, its needed then don't use it and remove it from the "Get All Users Filter" field
Group Support Tab
The preset for Active Directory preset on the User Group Support Tab is:
Users of Group Filter(optional): (&(objectCategory=user)(memberOf=$GROUP_DN$)) **** Not sure when this is used
Enter the LDAP query to return the groups list for a particular group. The group is specified by $GROUP$ macro, for example - (&(objectCategory=user)(memberOf=$GROUP$)). Groups information can be used by an integrated application for administration and authorisation purposes.
Group Base DN (optional): If this is Blank the group the "User Base DN *" Will be used as the search base. If the groups are in a particular location in the DS then use this field to help efficient searching in the DS.
Group search Filter (optional): (objectCategory=group) Enter the LDAP query to display the list of all groups, for example - (objectCategory=group).
The filter can be used by an integrated application for administration purposes to browse all groups to be considered as authorisation subjects. Use this in conjunction with the "Group Base DN" If this is used and the base DN is is set to a higher level in the DS then there is a potential to search for every single group in the DS, so try to make the Group Search DN as specific as possible
Group Name Attribute *: Enter the attribute to be used as group name. For example, cn. To verify this in the DS use LDAP browser and search for the group and check what attribute the group is using to uniquely identify itself
Group Of User Filter *: (&(objectCategory=group)(member=$DN$)) Enter the LDAP query to display the list of the groups for a particular user. The user is specified by $DN$ internal RSSO parameter when the Enable Group Retrieval check box is selected, this is a required field.
In a simple LDAP environment the preset "Active Directory" preset should be sufficient enough to enable a user to login with LDAP authentication and group retrieval. We'll take a look at this before looking at how to configure a more complex LDAP environments.
We'll be using Truesight TSOM as an example of LDAP authentication and use "Jose Mourina" as the user to login (jose01)
Summary of Steps:
- We'll be setting "Debug" level login in RSSO to see what searches are being made in relation to our configuration, this will help understand how RSSO is using LDAP and doing searches, debug should not be left on unless troubleshooting)
2. Log in with user jose01 (Jose Mourina) This user will initially not have access to the TSOM console
3. Use the default admin account to login (admin/admin12345) so we can make the necessary TSOM configurations
3. Configure TSOM to allow this user admin privileges in TSOM by including one of the group the user belongs to in TSOM Authorization profile. The user Jose Mourina will be removed from the operators group in Active directory and will be put in to a new group called "Technical Support"
- Configure TSOM Roles for the "Technical Support Group"
Ensure that both local and LDAP Authentication is configured in RSSO. We need local Authentication to be able to login with the default admin user, to make configuration chnages in TSOM
Set RSSO debug level on on the RSSO Admin console General--->Basic (fig 6)
Open a browser and go to the TSOM url and enter the user name of an LDAP user. You will initially get an unauthorised message (fig7). This is expected since the user does not belong to any group that has the correct permissions to login. If you are quick enough, go to the RSSO admin console--->Sessions Tab you will see the userID listed there, but it will disappear within 10 seconds and the login page will show again. This mean RSSO has done the authentication with LDAP successfully, but TSOM has not given the user's group permission to use the console (see Authentication vs Authorization above)
Looking at the RSSO server log (\Apache Software Foundation\apache-tomcat-7.0.62\logs\rsso.0.log) you will see the login request & authentication
DEBUG Thread_32 com.bmc.rsso.auth.Authenticator.doAuth(): Login request: jose01 - Request being made to RSSO for Authentication by the user when the user goes to the appliction url and the request is redirected to RSSO.
Search context parameters: ldapProviderUrl=ldap://clm-aus-022742.bmc.com:389, ldapAuthMechanism=simple, ldapSaslQop=AUTH, username=CN=JCKER,CN=Users,DC=sso,DC=bmc,DC=com] - RSSO makes LDAP connection call.
Searching user entry with filter: (&(objectCategory=user)(sAMAccountName=jose01)), search base: DC=SSO,DC=BMC,DC=COM, search scope: 2 - This the search being made in LDAP by RSSO if it returns no user, you can copy the search and use it in an LDAP browser to see if it does indeed return this user under the search base. This search is being done by the "User Search Filter" configuration in RSSO. The search Scope 2 part indicates sub-tree searching has been enabled in RSSO, search scope 1 would mean one level search.
Found user with DN: CN=Jose Mourina,CN=Users,DC=SSO,DC=BMC,DC=COM - User found in LDAP
Received token Id _198c84fb-5026-4481-bbd1-1bfe63014b6f for user JOSE01- Token created for the user, the token is stored in the RSSO database (IssuedTokens table) for referrals during the life of the user's session.
Searching groups by user JOSE01 with filter: '(&(objectCategory=group)(member=CN\=Jose Mourina\,CN\=Users\,DC\=SSO\,DC\=BMC\,DC\=COM))', search base: 'DC=SSO,DC=BMC,DC=COM', search scope: '2' and attribute 'cn' - RSSO searches the user's group you can use this filter in and LDAP browser by removing the "/" this search is done by the "Groups of users filter" configuration in RSSO.
The next step is to login to the TSOM with the default admin user and add the LDAP group the LDAP users belongs as an Authorisation profile. In the TSOM console go to
Administration-->Authorisation Profile-->Create a new Authorisation Profile--->Enter a Authorisation Profile Name--->click the Add button, RSSO will make a connection LDAP to bring back the groups from the LDAP server and the local RSSO User Management Groups (Roles). Search for the LDAP group the user belongs to and select it.
Now the group has been added to the profile, select the "Roles" tab --->Add-->The Search Roles Dialogue box comes up, select the roles you want to add for that profile and select OK. Depending on what Roles you have given to the Authorization Profile, you may also need to add objects. Once done click save and log out as admin.
Now if you login again with the LDAP user not only will the Authentication be done by RSSO, the Authorisation will also be done by TSOM(fig10). Any other LDAP users that belong to the same group will also be able to login and get the correct permissions to view the console.
If we take a look at the RSSO logs while going through the above process we can see
Searching all groups with filter '(objectCategory=group)', search base: 'DC=SSO,DC=BMC,DC=COM', search scope: '2' and attribute 'cn' - The search that RSSO is running in LDAP this is configured by the "Group Search Filter" field configured in the RSSO admin console
ERROR: Unprocessed Continuation Reference(s)
com.sun.jndi.ldap.LdapCtx.processReturnCode(Unknown Source) com.sun.jndi.ldap.LdapCtx.processReturnCode(Unknown Source) - Depending on how your LDAP system is configured you may get this message. When you search in AD, if AD thinks there are more information available in another place, it returns a referral [place to find more info] along with your search results.] This is generally nothing to be concerned about unless the information you are looking for is another place i.e. another AD system, if the returned value is not what you are expecting then the likelihood is the information is actually somewhere else, check with the LDAP administrator who should be able to help.
com.bmc.rsso.core.ldap.LDAPHelper.getSearchResultEntries(): All returned entries: [Performance Monitor Users, Users, Access Control Assistance Operators, Schema Admins, Purchasing, Technical Support] - The returned results from the LDAP search. If the result does not return what is expected take use the LDAP search and the search base and use and LDAP browser to see if then the correct results are returned.
Dealing with more complex LDAP environments & nested groups
Some LDAP environments can be very complex and large and the information in it may not always be where you expect. The best resource to help with this would be the LDAP Administrators since they would know how the system operates and is configured. But there are a few things that can be done and some rules to follow to make searching successful in Remedy Single Sign-On. A few rules to follow
1. Get an LDAP browser, so you can see the results of the search without the need to login to the application in question
2. Make the searches as Specific as possible if you know that the users will always belong in one OU & group and then point the search base to that, this will make the search more efficient
3. Use the RSSO server logs (in debug mode) to see what searches are being made to the LDAP server and use those searches and search base in a LDAP browser to see if the information you expect to return is returned
4. Have the LDAP Administrator's number contact details at hand
Some LDAP environments use the concepts of nested groups, while nesting groups in a multi domain environment reduces network traffic between domains and simplifies administration, it can also be challenging to do LDAP searches.
Consider the following example which we'll be using for the rest of this section.
"Harry C. ane" is a user in an OU called "UK". Harry is a member of the "Information Technology" group which in turn is a member of "Technical Support" group that is a member of the builtin "Viewers" group. Ultimately Harry will have the permissions to whichever group he belongs to and whatever groups that group is a member of. In this example we just want to know what group(s) Harry belongs to. With nested groups, although Harry is not directly a member of the "Viewers" group he will be a member of that group by association.
fig 10.1 User Harry and his groups hierarchy
Fig 11 shows Harry DS attributes where he is a MemberOf the "Information Technology" group.
Fig 12, shows all the users who belong to the "Information Technology" group listed by the "Member" attribute.
Fig 13, we can see the "Information Technology" group is also a "memberOf" the "Technical Support" group. We can drill down until we get to the "Viewers" group to get a better understanding of how the users and groups are related.
The question here is how do we construct our LDAP search to get nesting group results of Harry and where to start the search in the DS for the most efficient search?. Will our search base be "OU=Groups,OU=Demo Accounts,DC=SSO,DC=BMC,DC=COM"? The answer is no. If we did a search for Member = Harry in "OU=Groups,OU=Demo Accounts,DC=SSO,DC=BMC,DC=COM" it will only return the "Information Technology" group (fig 10.1) the other groups are in a different OU. That means in this instance our search base will be "DC=SSO,DC=BMC,DC=COM" (as this is a common path to all the groups), so its important to get a good understanding of where your user's and groups are in the DS and using an LDAP browser will help in do that. The most efficient way overall to do this would be to have the groups under one OU but we are not always in control of how the DS is designed.
Doing a nested group search for Harry we see all the groups he belongs to
Search: (&(objectCategory=group)(member:1.2.840.113522.214.171.1241:=CN=Harry C. ane,OU=UK,OU=Users,OU=Demo Accounts,DC=SSO,DC=BMC,DC=COM))
The "1.2.840.1135126.96.36.1991" is an LDAP rule object Identifier for more on this see Search Filter Syntax
fig 14 shows the result of running the query in LDAP browser where the Harry user's groups are returned
Configuring in RSSO
There are two presets in RSSO which can be used to quickly configure a particular LDAP design
Active Directory: To fill the LDAP filters with predefined values for the most common LDAP implementations.
AD Hierarchical: To search within nested groups. You may change filters to tune queries as well.
Its worth choosing one of the presets first to see if it works, If not you will need to fine tune the queries. Set the RSSO server log to debug and you can see what search RSSO is running in LDAP you can then use the search in an LDAP browser to see if it returns the correct results. The default "Groups of User Filter" with preset AD Hierarchical is (&(objectCategory=group)(member:1.2.840.1135188.8.131.521:=$DN$)) Where $DN$ is an internal parameter in RSSO to denotes the userID and should be left in even when doing custom queries.
(For information about the search fields in RSSO see "User Authentication Tab" & "Group Support Tab " sections above and the online documentation )
Login in to the Application (TSOM)
The Viewer role is a roles that exists in TrueSight by default, therefore we don't need to create an Authorisation profile. We can now login with user "harry01", RSSO will do the Authentication with the LDAP server, once authenticated, RSSO creates the user token, then send the userID & groups list back to TSOM for login. TSOM will then checks what the user is Authorised for by looking at the group list.
From the rsso.0.log (in debug mode)
DEBUG Thread_54 com.bmc.rsso.core.ldap.LDAPHelper.getGroupsByUser(): Searching groups by user harry01 with filter: '(&(objectCategory=group)(member:1.2.840.1135184.108.40.2061:=CN\=Harry C. ane\,OU\=UK\,OU\=Users\,OU\=Demo Accounts\,DC\=SSO\,DC\=BMC\,DC\=COM))', search base: 'DC=SSO,DC=BMC,DC=COM', search scope: '2' and attribute 'cn' - The search RSSO makes to the LDAP, we can take this search and its search base, put it in an LDAP browser and see if it returns the expected result, RSSO add "\" which needs to be removed before the search is run in an LDAP browser i.e (&(objectCategory=group)(member:1.2.840.1135220.127.116.111:=CN=Harry C. ane\,OU=UK,OU=Users,OU=Demo Accounts,DC=SSO,DC=BMC,DC=COM))
28 Oct 2017 04:47:01.909 DEBUG Thread_54 com.bmc.rsso.core.ldap.LDAPHelper.getSearchResultEntries(): All returned entries: [Technical Support, Domain Users, Viewers, Users, Information Technology] - Returned group list for user
[https-jsse-nio-444-exec-8] UserAccount Adding user with TenantName as harry01* - User Authorised in TSOM
Which user permission wins?
If a user belongs to more than one LDAP groups, lets take for example "Viewer" & Operator", which user permissions will be given to this user? This comes under the Authorisation part of the login process where the application will do access control. Some applications will take the UserID & LDAP group membership into consideration and use that to determine the permission of the user. Other applications like Remedy AR will take only the userID and do access control with its own internal groups and roles. You will have to check the documentation of the applications to see how the application itself deals with access control. In general if a user belongs to two different group the group with the most access permission will usually win out over the group with less permission.
How do I know if my LDAP search is efficient or not?
Probably the first time you'll know when your LDAP search is inefficient is when you get a call from the LDAP administrator.
You can get a glimpse of how fast your LDAP search is coming back with results by using an LDAP browser and count the seconds for the results to return. Check the RSSO logs to see the timestamps of the search and the returning results. Any LDAP search that takes more that 3-4 second to return results could be considered to be inefficient, but this will also depend on how the LDAP system is configured and how large it is.
RSSO will do LDAP searches when:
- The user requests to login, this will be a one time process until the user's token expires or the user logs out of the last application. If a user logs into another application in another tab in the same browser session, he will be able to use the same session he initially logged in with, so RSSO does not need to make another call to the LDAP server.
- When an application requires extra user information or group information from LDAP.
Some applications will give you an indication the search scope is too large (fig 16), and you want to try and narrow it down a bit normally by changing the search base or specifically adding a group name to the search if possible.
Check the RSSO server logs rsso.0.log file to see if there are any messages similar to:
SEVERE Thread_41 com.bmc.rsso.data.idps.IdPLDAP.getUserGroups(): LDAP error: [LDAP: error code 4 - Sizelimit Exceeded]
ERROR: [LDAP: error code 4 - Sizelimit Exceeded] - This is a sure way to tell your search can be improved.
You can narrow down slow logins into two section related to Authentication and Authorisation parts of the login process. If the login process is slow check the following
- How long it takes the userID to show up in the RSSO admin console sessions tab, if it takes a long time (if at all) then the problem is with the Authentication process
- If the userID session shows up in the RSSO admin sessions list in a acceptable amount, but the login is still slow then the issue is likely to be with either the communication of RSSO and the application, or the Authorisation of the user once Authentication has been done. The RSSO server log and the RSSO agent log & the application log will help narrow down where this bottle neck is occurring.
Sending logs to BMC Technical support for RSSO issues
While trouble shooting issues logs are very important, when raising cases with BMC provide the logs on the initial case opening. Follow these steps if possible when opening a case
- Set the RSSO server to debug mode. RSSO Admin console-->General tab-->Basic "Server Log level" = DEBUG
- If possible stop the RSSO service and delete the logs from /tomcat/logs then restart the Tomcat service (smaller logs are easier to read)
- Reproduce the issue document the date/time
- Zip up the logs from the following directories
RSSO Server: /tomcat/logs (all the logs from this directory)
Application side: /tomcat/logs (all the logs from this directory or at last the latest one's updated any logs with "rsso" in the name)
5. Document the steps to reproduce
6. RSSO server version, if an Authentication issue the Authentication type i.e. LDAP, AR, SAML. If you are able to login to the RSSO admin console open another tab in the browser and
go to https://rsso_server_name/rsso/config/server-status i.e. https://myrsso.bmc.com:8443/rsso/config/server-status and provide the output
7. Provide any other relevant information i.e. Load Balancer in use, the problem just started to occur or if its always been a problem
8. If an authentication issue specify which application i.e. Truesight, AR server, BAO etc..