Skip navigation
Share:|

In this post we are going to take a look at configuring & troubleshooting SAML authentication with Remedy Single Sign-On. We will take a look at the two most popular SAML implementation, Active Directory Federation Service (ADFS) and OKTA.

 

Versions used in this post

RSSO 9.1.04

ADFS V3

OKTA (latest sanbox dev version as of 04/2018)

Remedy AR server / Midtier 9.1.04

sso.bmc.com domain

 

In the post we'll take a high level look at what SAML is and how it works. We'll then continue to configure RSSO with OKTA and ADFS. Finally we'll take a look at how to troubleshoot authentication problems with SAML.

 

What Is SAML?

SAML (Security Assertion Mark up Language) is a is an Extensible Markup Language (XML) standard that allows a user to log on once for affiliated but separate web applications.

The purpose of SAML is to provide centralized management of userid and password to allow access to applications from different vendors.  SAML uses XML to create assertions for users. The assertions includes information for access to application, token for the user along with other information such as user’s location, role etc..

 

The two most popular implementations using the SAML protocol are OKTA and Microsoft's ADFS

 

The are three main components in SAML implementation

• User. The end user who requests a service the service request can include access to sales force, webex MS 360 etc.  (User Browser)

• Service provider (SP). This is the application which provides the user with the service they request, it also sends authentication requests to the IDP to authenticate the user (RSSO)

• Identity provider (IDP). The central database for users, does the Authentication of the user and send the assertion back to the service provider to allow access for the user. (ADFS, OKTA)

 

SAML Process Flow

The SP hosts and protects the services that the user accesses. Remedy SSO is configured as an SP for BMC products. The IdP authenticates users and provides details of the authentication information to the SP.

The following table provides the workflow for the SAMLv2 logon authentication that is SP initiated:

StageDescription
1User accesses the protected application from a mobile device or through a web browser.
2Web Agent redirects the user to Remedy Single Sign-On (Remedy SSO) console.
3Remedy SSO sends a request to IdP to authenticate user.
4IdP presents a login form to user for authentication.
5User enters valid credentials.
6.IdP performs user authentication.
7.IdP forms authentication response and sends it back to the Remedy SSO server.
8.Remedy SSO server processes authentication response, validates it, and extracts the assertion that carries user data.
9.Remedy SSO creates a session for the user.
10.The user is allowed to access the application.

 

 

Identity Provider:  Identity Provider (IDP) maintains, and manages identity, it provides authentication as a service. IDP usually uses a directory service at the backend as its user store. An IDP in terms of SAML can be any system that 1. Provides Identity & Authentication services 2. Uses the SAML v.2 Protocol

 

Service Provider: Service Provider (SP) Is a system entity that receives and accepts authentication assertions in conjunction with a single sign-on (SSO) profile of the Security Assertion Markup Language (SAML).

 

NameIDFormat: - The providers in a SAML environment (Identity Provider & Service Provider) needs a common way to identify the userID attribute when sending SAML assertions. The NameID format specifies the common format that providers will use. There are times when there are more that one NameID format in the assertion, depending on what format is being used will determine which one will get used by the providers, Commonly used NameID formats are

 

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified - This is the default NameID format. This is left to the IDP to decide how to interpret the assertion elements and it assumes the SP knows how to parse the format data respond from the IDP

 

urn:oasis:names:tc:SAML:2.0:nameid-format:transient - Indicates that the content of the element is an identifier is treated as a temporary value by the relying party.  A transient identifier is temporary and no data will be written to the user's persistent data store.

 

urn:oasis:names:tc:SAML:2.0:nameid - format:persistent - A persistent identifier is saved to a particular user's data store entry as the value of two attributes

 

 

Configuring OKTA With RSSO

In this section we are going to have a look at configuring SAML Authentication with RSSO using OKTA.  We will be going through the whole process from creating the RSSO OKTA app to configuring RSSO to use it.

 

TIP: If you are configuring SAML OKTA on a dev system, it might be useful to create yourself a developer OKTA account, then you can test the configuration fully without having to ask the OKTA administrators to keep changing parameters as they may not be readily available. See attached doc oktadevsignup.docx below for instructions on how to sign-up for an OKTA accoung. Going through this process will also have the added benefit of showing how the OKTA saml authentication process works with hands-on experience plus you can follow along with the rest of this post.

 

Required information for OKTA SAML Configuration:

RSSO server service url: https://rssolb.bmc.com:8443/rsso/reciever  (The example we will use in this post)

Service Provider Identity: RSSO  (The example we will use in this post)

 

Summary of steps

1. Login to OKTA

2. Create the RSSO OKTA app

3. Provide the RSSO OKTA app with the relevant rsso server information

4. Import the OKTA Meta data in RSSO

5. Test the application login

 

In this example RSSO will be the service provider (SP) and OKTA the Identity Provider (IDP). The following procedure is an OKTA administrator function, and should be sent to the OKTA administrators to action. If you have created an OKTA dev account you can also follow this procedure to create the RSSO application in OKTA. Since most companies have an LDAP system with their users information in we will also be integrating OKTA to an internal LDAP system which is active directory.

 

Vid1. Goes through the procedure of login into OKTA and start creating a new application.

 

Once we've logged in and created the RSSO app we will come to the OKTA SAML integration page. Here we will need to provide the information of our RSSO system. In the "Single sign on URL" field enter in the url to the RSSO server /reciever  i.e https://rssolb.bmc.com:8443/rsso/receiver . Leave the "Use this for Recipient ULR and Destination ULR" check box ticked.

In the "Audience URI (SP Entity ID)" field enter the RSSO SP Identity, this can be found in the RSSO admin console under General-->Advanced (fig1)

 

Fig1. Shows the configured SP name of the RSSO configuration.

If you don't have an SP Identity name at this point then enter one, the SP name can be anything but the recommendation is to set a name which will identify RSSO quickly in this example the SP Entity ID is "RSSO"

 

We will leave "Name ID format" to "Unspecified" & "Application username" to "Okta username", we can change these later if required to meet organisational requirements. Click the "Show Advanced Settings" link. Under the advance settings we won't change anything at the moment, we can change these fields at a later point depending on organisational policies, these advanced options will form part of the OKTA's meta data that we'll need to import into RSSO later on in the configuration process .  We can preview the SAML Assetion, this will shows the IDP's meta data, if you want to see this click the "Preview the SAML Assertion Button". To see a description of each field on the OKTA SAML integration page click the question mark button next to the field.

 

Fig2. OKTA SAML integration page filled out.

 

Click Next on the OKTA SAML integration page. On the next screen click "I'm a software vendor. I'd like to integrate my app with okta" since we are at a development stage, if you are an OKTA customer then select the option and fill out the details requested. Then click "Finish" DO NOT click the "Submit your app for review" nothing bad will happen its just that we won't be able to use the app until OKTA has verified it.

 

You will be redirected to the "Sign On" page (fig3)

 

Fig3.

On this page click "Identity Provider metadata is available if this application supports dynamic configuration" button. This will show you and xml formated page with the OKTA meta data in, we will need this data for the RSSO configuration later on in the configuration process. You can either copy the url in the address bar or save the file locally on to the desktop (fig4 )

 

Fig4.

Users & Groups

There are two methods you can use in OKTA to use for user logins

 

1.OKTA's internal user store

2. LDAP/Active Directory integration

 

Internal User Store

 

Vid2. The following video with go through the process of creating a user in the OKTA internal user store. We can use this user to login to our application later on

 

LDAP/Active Directory Integration

 

Vid3. This video goes through the process of integrating LDAP/Active directory with OKTA so your organisation's users and groups will be available in OKTA. You will need to have access to the LDAP server. This is a function of the LDAP/AD administrators and should be actions by them.

 

 

Now that we have our user's in OKTA either created in the internal user store or integrated with LDAP/Active directory, our next step is to do the integration with RSSO.

 

Assigning Applications to users in OKTA

In OKTA we have to assign our newly created application either to an individual user or group, this process gives permission to a particular user or a group of users to use the application. Since this is an Single Sign-on application the users will not see the application directly, instead when they login to an application they will see the OKTA login page and once successfully logged in will see the application they have called

 

Vid4. Goes through the process of giving users or groups permission access to the RSSO application

 

OKTA integration with RSSO

For this example we are going to create a new realm in RSSO called "OKTASAML"

1. Login to the RSSO admin console go to General-->Advanced

2. Under "SAML Service Provider" ensure the following fields are filled out

  • SP Entity ID - This is the ID that the service provider (RSSO) will be known to OKTA, this should have been filled out already when configuring the OKTA portion (see above)
  • External URL - The RSSO service URL. Location to the RSSO server /rsso at the end, this url needs to be resolvable on the network
  • KeyStore/Password/Signing Alias - The location of the keystore file/the keystore password & the signing alias which will be the certificate used by RSSO to present to OKTA for verification (see  online documentation Setting SP signing certificate for SAML authentication

 

Fig5. Shows the basic (prerequisite) configuration for SAML in RSSO

3. On the RSSO admin console go to Realm-->New Realm (as mentioned we are going to create a new realm called "OKTASAML", but any realm can be used such as the "*" realm)

4. Give the new realm a name. For the application domain in this example we are going to enter "redmymtokta.bmc.com" this needs to be resolvable on the network, this will be the url we are going to access the Remedy Midtier with i.e. http://redmymtokta.bmc.com:8080/arsys, when this url is called it will tell RSSO to use the OKTASAML Realm and what ever authentication is configured (fig6).

 

Fig6.  Shows the configuration of the application domain, normally the application server name or the load balancer FQDN

5. Go to Authentication on the Authentication Type drop down select SAML

6. Click Import, here you have two options either enter the url to the OKTA IDP meta data or if you have download the meta data .xml file choose "Import from local file" option

In this case with are going to use the URL to the meta data (see above in the OKTA configuration portion on how to get the meta data) click Import

7. Once the import has been done, the OKTA meta data will be imported and the IDP fields will be filled out

8. Because we need to sign our OKTA request select the "Sign request" option

8.1 OKTA unless you have changed the configuration will send userID in the email format user@domain.com for AR server unless the user is in that format in the user or people form

you will get an error login in, you will have to check the format of the users in the CTM:People form or User form and use one of the RSSO "User ID Transformation" options  i.e

"Remove Domain" Or "Remove email domain" In this example since the user in AR is in the email format we won't need to select this option

9. Click ADD

10. Click edit on the realm scroll down and clock "View metadata" here you will see the SP meta data (fig7)

 

Fig7. Shows the SP (RSSO) meta data after configuration

Vid5. Shows the process of locating the OKTA metadata, importing the OKTA metadata into RSSO & view the RSSO SP metadata

 

We have now finished the basic configuration for integrating RSSO and OKTA using SAML and should be able to login to the application (Remedy Midtier) via RSSO using SAML.

 

Vid6. Shows login in of the midtier via RSSO integrated with SAML (Local OKTA user and Active Directory user) and also how to use the "user ID transformation" option in RSSO

 

OKTA Advance options

OKTA has some advanced options which you might want to make use of. In this section we will take a look at these options. In general if any of the basic or advanced options are changed you will need to re-import the OKTA's meta data into RSSO.

 

You can get to the advance options page by login into the OKTA admin console --->Admin-->Applications--->select the application--->Genral tab-->Click edit on the SAML Setting tab-->Click Next on the General settings--->Once on the SAML click show advance settings (fig)

 

Fig8. Advanced settings in OKTA

 

Response: Determines whether the SAML authentication response message is digitally signed by the IDP or not. A digital signature is required to ensure that only your IDP generated the response message. The default and recommended setting is "Signed"

 

Assertion Signature: Determines whether the SAML assertion is digitally signed or not. A digital signature is required to ensure that only your IDP generated the assertion

 

Signature Algorithm: Determines the signing algorithm used to digitally sign the SAML assertion and response

 

Digest Algorithm: Determines the digest algorithm used to digitally sign the SAML assertion and response

 

Assertion Encryption: Determines whether the SAML assertion is encrypted or not. Encryption ensures that nobody but the sender and receiver can understand the assertion

NOTE: RSSO 9.1.04 and below does not support this function. The support for Assertion Encryption is scheduled for RSSO 1805 (May 2018)

 

Authentication Context Class: Identifies the SAML authentication context class for the assertion's authentication statement

 

 

Troubleshooting OKTA SAML & RSSO

There are many ways in which authentication can break between OKTA SAML and RSSO. The following section will not describe these situation (Will show a couple of common issues), but will instead go through the best approach to troubleshoot these problems and document what files to send to BMC support if you are still not able to find a solution. If you are seeing a particular error the first step is to search the BMC support pages, knowledge base and communities. The troubleshooting steps for SAML will also be valid for a whole host of other SAML IDP such as NetScaler.

 

We'll take a look at the RSSO server logs, the OKTA system logs, Fiddler, SAML tracer and the application agent log.

 

SAML Tracer/Chrome Panel: Good tool to see SAML requests and responses from SP and IDP, limited in its functionality but is more intuitive than fiddler. At the time of writing is only available for FireFox browser its equivalent for Chrome browser is SAML Chrome Panel

 

Fiddler: Best all round tool to troubleshoot SSO related, network and sessions issue. Can be complex and some company policies will not allow fiddler to be installed as it can pose a security risk.  NOTE: Do not install fiddler on a server as it can pose a security risk because the fiddler Root certificate needs to be trusted for decryption.

 

RSSO Server Logs / Application Agent Log: All logs related to RSSO can be found in the /tomcat/logs directory of the RSSO server and its integrated web applications (Remdy Midtier, BAO, TrueSight)

 

OKTA System Logs: The OKTA system logs would be a place where you would look if its determined that a SAML response is not coming back correctly or the OKTA IDP can not process the SAML request (You'll use one of the tools above to determine this). You might not have acces to see these logs if you are not an OKTA admin, so you will need to speak to the OKTA administrator to take a look at the logs on the OKTA side.

 

If we have followed the above configuration process and are not able to login, the first thing we need to do is to looks at what the error message looks like, you can often tell very quickly what component in the process is throwing out the error message just by looking at the screen the message is being displayed on & the url in the browser, you can then start troubleshooting from that component whether its RSSO, OKTA(SAML) or the application (vid7 ).

 

Vid7. Shows how to differentiate different screens when a problem occurs so you can identify quickly where to start the troubleshooting process

 

Vid8. Shows troubleshooting with SAML tracer plugin for browser

 

Vid9. Shows how to troubleshoot sessions in fiddler

NOTE: Do not install fiddler on a server since this posses a security risk, where the fiddler certificate needs to be trusted. If you do install it on a server make sure to remove the FIDDLER certificate from the trusted certificate

 

 

 

Fig9. Fiddler icons legend

 

RSSO Server Logs / Application Agent Log

For both the RSSO server and the integrated applications (Midtier, BAO, Truesight) the RSSO related logs can be found in the /tomcat/logs directory. The majority of the time when there is a problem with the SAML login process we will need these logs in debug mode.

 

rsso.0.log - The RSSO server log found in tomcat/logs directory

rsso-agent.0.log - This is the agent log found on the integrated application in the tomcat/logs directory. The RSSO agents at most does the redirection to RSSO server and in terms of SAML authentication does not take part in the authentication process. The default RSSO agent log level should be sufficient enough for troubleshooting purposes.

 

RSSO Server Log debug - To set the RSSO server log into debug mode, login to the RSSO admin console -->General-->Basic and change the "Server Log Level" to DEBUG, there is no need to restart the RSSO tomcat service, you should start seeing debug messages in the rsso logs after 30 seconds.

 

RSSO Agent logs debug - Log level should be left at default, the RSSO agent will log most  Info, Warnings and Error messages

 

Fig10. Shows the location on the RSSO admin console to set the RSSO server to "DEBUG" switch back to "INFO" when not troubleshooting

 

 

 

Active Directory Federation Sevices (ADFS) SAML

Microsoft Active Directory Federation Services (ADFS) is an extension of Active Directory. While active directory serves to contain user identification, authentication and authorization within its own organisation and domain boundaries, its extension Federation Services can be used to cross these boundaries.

 

The basis of Federation Services is to provide a trust relationship between two organisations or entities, where one side can be used to hold user identification and the other side provides applications and resources.

 

ADFS uses a claims-based access-control authorization model to maintain application security and to implement federated identity. Claims-based authentication involves authenticating a user based on a set of claims about that user's identity contained in a trusted token. Such a token is often issued and signed by an entity that is able to authenticate the user by other means, and that is trusted by the entity doing the claims-based authentication.

 

In this section we are going to have a look at configuring SAML Authentication with RSSO using ADFS

 

Required information for ADFS SAML Configuration:

RSSO server service url: https://rssolb.bmc.com:8443/rsso (The example we will use in this post)

Service Provider Identity: RSSO (example we will use in this post)

ADFS server name

ADFS meta data either url or .xml file holding the meta data (Ask the ADFS administrator for the metadata url)

Signing certificate

 

When configuring RSSO and ADFS SAML you can either configure RSSO first or create the ADFS relying party trust, either way will work. In this post we will start by creating the relying party trust then continue to configure RSSO.

 

Creating Relying Party Trust on ADFS

To enable RSSO to use ADFS we will need to create the relying party trust for RSSO on the ADFS server. In the following video we will run through this. This is a function of the ADFS administrator, these steps should be sent to the ADFS administrator to action. You will also need to to send the ADFS administrator the Service Provider IdentityID.

The Service Provider identity ID can be configured on the RSSO admin console "General--->Advanced" tab. If you are going to configure ADFS SAML under the none default realm "*" you will need to add "/RealmName" to the SP entity ID, for example in this post our entityID is called "RSSO" but later on we will configure a realm in RSSO for SAML authentication called "ADFS" so our entityID will be "RSSO/ADFS" We do this to separate one tenant/realm/domain authentication from another  (fig11) The rest of the information on the "Advanced" tab will be configured later, but the ADFS admin will need the SP entityID to be able to create the relying party trust.

 

Fig11. shows the SP entity ID. Because we are going to create a realm for SAML ADFS called "ADFS" our SP entity ID will be "RSSO/ADFS"

 

 

Vid10. Creating relaying party trust for RSSO

 

ADFS RSSO Claims rule template

Copy the ADFS claimes rule template below for the ADSF claims rule (Fig11)

 

* Put in the ADFS server FQDN

** Put in the RSSO service provider name, if the non default "*" realm is being used, then add the "SP entity ID / Realm Name"

 

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]

=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/namequalifier"] = "*<ADFS_Server_Name>/adfs/services/trust", Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/spnamequalifier"] = "**<SP_Identity_ID>");

 

Fig12. Shows ADFS claim rule for RSSO

 

Relying Party's Federation Meta Data Url

This is the location to the RSSO meta data. If you have not configured RSSO yet, you can still put this url into the "Relying Party's Federation Meta Data Url" field when creating the relying party

 

*RSSO server's FQDN

** RSSO server port number

*** If you are using the default "*" realm use "*" for the realm name, else use the realm name as defined in RSSO (fig13)

 

https://*<RSSO_SERVER_FQDN>:**<PORT>/rsso/getmetadata.jsp?tenantName=***<REALM_NAME>

 

Fig13. Shows entry of the RSSO SP meta url

 

 

Configuring RSSO (Service Provider) For ADFS

After creating the relying party trust on the ADFS server, the next step is to configure RSSO to use it. In this blog we will be creating a realm called "ADFS" in RSSO where we will be configuring SAML (ADFS) authentication.

 

Creating The Keystore and Certificate For SP Signing

Most ADFS implementations require the request to be signed by the Service Provider, you can confirm this with the ADFS administrators. The first thing we need to do is to create the keystore and certificate  on the RSSO server to use for signing the SAML request going to ADFS.  Follow the Setting SP signing certificate for SAML authentication for instructions on how to do this.

 

Configure Service Provider Options

After the keystore has been created, the next step is to configure the SP configuration on the RSSO admin console login to the console and go to General -->Advanced

In the "Service Provider" section we will fill out the the service provider information (fig13).

 

SP Entity ID: This is the unique identity of this provider, it can be any name you like, however if the relying party trust was created first then this name will need to match what was configured on the ADFS side

 

External URL:  This is the url SAML (ADFS) will respond to RSSO on, this can be considered as the external Service url. Since SAML support cross domain authentication, its recommended that this url uses SSL, so tomcat will need to be configured to use SSL.

 

TIP: Unless there is a company wide policy to use http internally then both the Service URL and the EXternal URL should be using SSL for more secure communication

 

Keystore FIle: This is the full path of the keystore which was created earlier. The full path is needed only if the keystore location is not in the "\webapps\rsso\WEB-INF\classes\" folder on the RSSO server

 

Keystore Password: Enter the password that was used when the keystore was created

 

Signing Key Alias: The alias name used when the keystore was created, the alias name is created with the "-alias sp"  parameter when creating the keystore

 

After these fields are filled out hit "Save" There is no need to restart the RSSO service after this.

 

Fig14.  The filled out information for the Service Provider with examples documented at the beginning of this post

 

 

Create New Realm For SAML ADFS

This portion is optional but, but is normally done when one RSSO server will service different customer's or organisational departments. If RSSO is configured for only one organisation then usually the default "*" will be sufficient and there is no need to create a new realm.

 

In the example of this post, when we created the relying paty trust our SP Identity was called "RSSO/ADFS", we've already put our SP name (see above) as "RSSO", now we will need to create a realm called ADFS, so the relying party trust will know which realm to call. This is useful if one RSSO server is serving multiple ADFS severs maybe from a different organisation or department. On the RSSO admin console go to "Realm--->Add Realm Button (upper right hand side)" in the general tab on the create realm screen fill out the RealmID, Application Domain & After Logout URL  (fig)

 

Realm ID: This is the unique realm name, can be anything but be aware that if you have created the relying party trust already and if RSSO will be configured in a multi realm environment then the name must match what was configured in the relying party trust

 

Application Domain: Fill out the application server's FQDN for example if your application is remedy midtier and the midtier url is https://midtier123.bmc.com:8443/arsys then the application domain will be midtier123.bmc.com. This is the same if the application is accessed via load balancer  for example if the midtier is accessed with the following url https://mymidtierLB.bmc.com/arsys  then the application domain will be mymidtierLB.bmc.com

 

After Logout URL: The logout url is used to redirect users to another url after they have logged out needs to be in http format i.e. http://www.bmc.com will take the users to BMC web page after log out

 

After filling out the above three fields go to the "Authentication" tab on the "Authentication Type" drop down list select local  then hit "Add" we will continue the rest of the configuration for ADFS authentication in the next

 

Fig15. New realm creation (Example in this post : ADFS)

Configuring SAML Authentication

The next step in this process is to create the SAML authentication, this include importing the IDP meta data, configure the User ID Attribute , select if the requests to the ADFS server needs signing and check if the SP meta data has been published correctly (vid11 )

 

Vid11. Goes through the process of creating the authentication for SAML (ADFS)

 

Parameters list

Header 1Header 2
ImportOpens a dialog box to import the IdP metadata. You can provide a URL or specify a local file to import the data.
IdPEntity ID

IdP entity ID that is obtained from an external IdP provider such as AD FS or Okta.

Examples: http://adfs.local/adfs/services/trust , http://www.okta.com/exk4mi22tbfhiAnIn0h7

Login URL

Login URL of the IdP that is obtained from an external IdP provider such as AD FS or Okta.

Examples: https://adfs.local/adfs/ls , https://dev-726770.oktapreview.com/app/bmcdev726770_oktaidp_1/exk4mi22tbfhiAnIn0h7/sso/saml

Logout URL

URL provided by IdP to which the user is redirected for SP initiated logout. If you do not provide any value in this parameter, then the value in the Login URL field is used for both login and logout endpoints.

Logout Response URLURL provided by IdP to which the user is redirected for IdP initiated logout.
HTTP Binding TypeHTTP binding for SP initiated logout URL.
IdPSigning CertificateSigning certificate that is used by Remedy SSO to sign requests that are sent to IdP.
User ID AttributeUser ID attribute that is used to retrieve the user id from the specified attribute in the SAML response. If it is not specified, the NameID will be used as the user id.
NameID Format

Defines the name identifier formats supported by the service provider. Name identifiers are a way for providers to communicate with each other regarding a user.

The Name ID format list is an ordered list, the first Name ID has the highest priority in determining the Name ID format to use. If the user does not specify a Name ID to use when initiating single sign-on, the first one in this list is chosen and supported by the remote Identity Provider.

A persistent identifier is saved to a particular user's data store entry as the value of two attributes. A transient identifier is temporary and no data will be written to the user's persistent data store.

Note: For linking user accounts from SP and IdP (Remote Identity Provider) together, after logging in,the persistent nameID format must be on the top of the list.

Auth Context CompareSelect an option (exact, minimum, maximum, better) from the list.
Auth ContextAuthentication context that maps the SAMLv2-defined authentication context classes to the authentication level set for the user session for the service provider.
Auth Issuer

Issuer details that are used by SAML authentication request XML to inform the IdP about the entity ID of the service provider for this request.

If the value is not specified, by default SP entity ID of the current realm will be used as Issuer in SAML authentication request.

Assertion Time SkewTime offset between Remedy SSO and IdP. The value is specified in minutes.
Assertion Time FormatTime format used by assertions.
Sign RequestSpecifies whether the IdP requires authentication request to be signed.
Force AuthenticationThe option to select enforce authentication
Enable Single LogoutEnables SP initiated single logout, that is, if the user logs out from one application, the user gets logged out from all applications that share the same session.
Sign Response

Specifies whether Remedy SSO requires a signed response from the IdP.

Remedy SSO validates the signature from the authentication response.

Compress RequestSpecifies whether to compress the SAML message to save space in the URL.
View MetadataDisplays Remedy SSO metadata that is configured in the SP Metadata Template field. If any required parameter is not entered, the system shows an error message for that parameter.
Authentication Request TemplateTemplate used for SAML authentication request. You can select Default or Custom and also edit the template if required.
SP Metadata Template

Service provider metadata template. You can select Default or Custom and also edit the template if required.

If you are enabling the IdP initiated single logout feature, include the following information in the SP metadata template after the <AssertionConsumerService> tag and then update the settings of the IdP with the new metadata.

<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="%%LOGOUT_REQUEST%%" ResponseLocation="%%LOGOUT_RESPONSE%%"/>

where,

 

 

Testing ADFS SAML Login

 

Vid12 Testing the ADFS/SAML login after configuration

 

 

ADFS Authentication Policies & RSSO configuration

ADFS provides functionality to use Windows Based Authentication (seamless login) & Form Based Authentication for users who have logged into the domain. ADFS also provides Form Based Authentication for users who are external and has not logged into using a windows account.

 

Windows Authentication: Provides seamless login functionality. If a user has logged into the domain using their windows account, ADFS will use this windows account to authenticate the user with the application e.g. Remedy Midtier or TrueSight, so users do not need to enter a user name and password. This can only be set of internal users.

 

Forms Based Authentication:  This authentication method can be used for both Internal & External users (users who have not logged into the domain with a Windows account). The Forms Authentication will request a user name and password from the user regardless of if they have logged into the domain or not.

 

In general the configuration will be Extranet is configured for Form Based Authentication & Intranet will be set to Windows Authentication  (fig15)

 

Fig15 Shows the global policies configuration for ADFS

 

When using this configuration we have to change the Authentication Context "urn:federation:authentication:windows". This will allow external users to hit the form based ADFS authentication screen (fig) while internal users will use Windows Integrated login (seamless login)  (fig16)

 

Fig16. Shows Auth Context in RSSO configuration changed to "urn:federation:authentication:windows" to allow Form Based Authentication for external user and Windows Authentication login for internal users

 

 

Fig17. Shows the Form Based Authentication Login

 

IDP Initiated Login & Single Logout

In an IdP initiated login, a user gains access to the IdP site first and then clicks on one of the services provided by the remote Service Provider (SP). After the user selects the required service, the IdP initiates the authentication process.

IdP initiated login has the following advantages:

  • In an SP initiated login, users need to use different links to gain access to different services provided by a service provider. Hence they might need to bookmark all links. The advantage of using IdP initiated login over SP initiated login is that end users need to use only one link, that is the IdP link, to gain access to any services provided by a service provider. For example, if the IdP is AD FS 3.0, the user might enter the URL https://adfs-server.contoso.com/adfs/ls/IdpInitiatedSignon.aspx to gain access to the IdP site.
  • Users get the same SSO experience for gaining access to BMC products and the third-party products as they click the same IdP link to gain access to these products.

 

IdP initiated single logout

In the IdP initiated single logout (SLO), if a user logs out from any of the applications belonging to a single login session, the user gets logged out from all applications, BMC and third-party, that belong to the same session. IdP initiated logout is triggered when the user clicks a logout option from the IdP logout page.

IdP initiated SLO has the following advantages:

  • Customers get the same logout experience for both BMC and third-party products as they click the same link on the IdP site to log out from IdP and all applications provided by different SPs that share the common SSO session.
  • When the user logs out from IdP, the user gets logged out from all other logged in applications including Remedy SSO. After logging out, if the user tries to gain access to any of the applications, the user is authenticated again.

 

Summary of steps to configure IDP initiated login & Single Logout with RSSO

  • Import IDP meta data into RSSO
  • Enable "Single Log Out" option in RSSO SAML configuration
  • Create relaying party trust for RSSO on the IDP
  • Create relay state for applications url
  • Enable Single Log Out option on the IDP

 

Vid13. goes through the process of configuring IDP initiated login and Single Logout with RSSO and ADFS

 

URLs needed for IDP initiated login and Single Logout:

 

Relay State URL: https://<RSSO Server Name>:<port>/rsso/receiver/<Realm Name>?RelayState=<Url Location>

  • RSSO Server Name: Fully qualified url of the RSSO server or the Load Balancer URL to RSSO
  • Port: Web port of the RSSO server
  • Realm Name: If creating the RSSO SAML authentication in a different realm other than the default "*"  realm, then add the realm name. If using the default "*" realm then there is no

        need to put in the realm name (see examples below)

  • URL Location: This is the redirect url you want to go to after the login to the IPD is done and session is created in RSSO.

Examples - https://rssolb.bmc.com:8443/rsso/receiver/?RelayState=https://clm-aus-022742.sso.bmc.com/rssostuff.htm    (Relay state url with the default "*" realm)

                  https://rssolb.bmc.com:8443/rsso/receiver/Myrealm?RelayState=https://clm-aus-022742.sso.bmc.com/rssostuff.htm  (Relay state url with a realm called "Myrealm")

  • Single Logout URL:  The default Single Logout URL for ADFS is https://<ADFS server name>/adfs/ls/?wa=wsignout1.0
  • ADFS server name: The server name of the ADFS server or farm name

 

Example - https://clm-aus-022742.sso.bmc.com/adfs/ls/?wa=wsignout1.0 

 

Troubleshooting SAML ADFS & RSSO

There are many ways in which authentication can break between ADFS SAML and RSSO. The following section will not describe these situation (will show a couple of common issues), but will instead go through the best approach to troubleshoot these problems and document what files to send to BMC support if you are still not able to find a solution. If you are seeing a particular error the first step is to search the BMC support pages, knowledge base and communities.

 

We'll take a look at the RSSO server logs, the ADFS system logs, Fiddler, SAML tracer and the application agent log.

 

SAML Tracer/Chrome Panel: Good tool to see SAML requests and responses from SP and IDP, limited in its functionality but is more intuitive than fiddler. At the time of writing is only available for FireFox browser its equivalent for Chrome browser is Saml Chrome Panel

 

Fiddler: Best all round tool to troubleshoot SSO related, network and sessions issue. Can be complex and some company policies will not allow fiddler to be installed as it can pose a security risk.  NOTE: Do not install fiddler on a server as it can pose a security risk because the fiddler Root certificate needs to be trusted for decryption.

 

RSSO Server Logs / Application Agent Log: All logs related to RSSO can be found in the tomcat/logs directory of the RSSO server and its integrated web applications (Remdy Midtier, BAO, TrueSight)

 

ADFS System Logs: The ADFS system logs would be a place where you would look if its determined that a SAML response is not coming back correctly (you'll use one of the tools above to determine this). You might not have acces to see these logs if you don't have access to the ADFS server you will need to speak to the ADFS admins to either have a look for error messages relating to the RSSO SP or ask for permission to view the logs.

 

If we have followed the above configuration process and are not able to login, the first thing we need to do is to look at the error message, you can often tell very quickly what component in is spitting out the error just by looking at the screen the message is being displayed on & the url in the browser, you can then start troubleshooting from that component whether its RSSO, ADFS or the application (vid13)

 

Vid13. Quick troubleshooting method identifies where to start the troubleshooting process

 

Vid14. Shows troubleshooting with SAML tracer plugin for browser

 

Vid15. Shows how to troubleshoot sessions in fiddler

NOTE: Do not install fiddler on a server since this posses a security risk, where the fiddler certificate needs to be trusted. If you do install it on a server make sure to remove the FIDDLER certificate from the trusted certificate

 

 

 

Fig Fiddler icons legend

Vid16. Shows troubleshooting with the ADFS Event Logs

 

Event Viewer Security Search By User Filter:

 

<QueryList>

<Query Id="0" Path="Security">

<Select Path="Security">* [EventData[Data[@Name='TargetUserName']='USERNAME']]</Select>

</Query>

</QueryList>

 

 

RSSO Server Logs / Application Agent Log

For both the RSSO server and the integrated applications (Midtier, BAO, Truesight) the RSSO related logs can be found in the /tomcat/logs directory. The majority of the time when there is a problem with the SAML login process we will need these logs in debug mode.

 

rsso.0.log - The RSSO server log found in tomcat/logs directory

rsso-agent.0.log - This is the agent log found on the integrated application in the tomcat/logs directory

 

RSSO Server Log debug - To set the RSSO server log into debug mode, login to the RSSO admin console -->General-->Basic and change the "Server Log Level" to DEBUG, there is no need to restart the RSSO tomcat service, you should start seeing debug messages in the rsso logs after 30 seconds.

 

RSSO Agent logs debug - Log level should be left at default, the RSSO agent will log most  Info, Warnings and Error messages

 

Fig18. Shows where to set DEBUG level for the RSSO server

 

 

 

What Logs and Information To Send BMC Support

If you come across a particular problem with RSSO & SAML authentication, when raising a case with BMC support the following details will help expedite resolution.

 

1. Version of RSSO

2. If SAML authentication has been working before and now does not, consider what may have changed in the environment, i.e. patches/network changes applied before the issue started to occur

3. Description of the problem including error messages seen (screen shot if possible)

4. RSSO server log in "DEBUG" mode, you can set this on the RSSO admin console "General Tab--->Basic" Screen the logs can then be found on the RSSO server in /tomcat/logs

generally its best to zip up all logs in this directory that has been updated from the time frame the problem occurred

5. Which IDP you are using i.e. ADFS, OKTA

6. Date/Time the problem occurred

7. A userID which is being used if its a session problem

8. Fiddler trace or SAML Tracer logs (see videos above on how to capture and export these)

 

Sometimes BMC support will need access to the IDP for further troubleshooting, so the SAML administrator maybe asked to attend a call.

Share:|

In this post we'll take a look at configuring Kerberos for authentication for with Remedy Single Sign-On & troubleshooting any errors we may come across along the way.

 

Versions used in this blog

RSSO 18.02 build 9 (load balanced rsso.bmc.com)

Active Directory Windows 2012

Remedy Midtier 9.1.0 (load balanced remedy.bmc.com)

The servers are in a domain called bmc.com, the users in Active Directory will be in a different domain called diffdom.com

 

Why are we configuring users in a different domain to the servers?

There has been a few support calls raised with BMC support with this type of configuration, so we'll run through this as the configuration in this post. If the users and servers are in the same domain, it will be configured in exactly the same way.

 

Creating the Service Principle Name for RSSO on the KDC

There are a few ways to creating service principles on the KDC to use with RSSO. But the format of the creation will ultimately be the same. To start with we need to create a user in Active Directory. We can either create a standard user or a managed service account, either one will be valid, in this post we'll cover creating a user in the normal manner and map a service to it. This procedure a function of the domain administrators and should be sent to them to action.

 

In our case we'll be creating a user account called "MYRSSOPRINCIPLE" as a standard user in active directory. We'll set the password options "User Cannot Change Password" and "Password Never Expires" The password expiry will be dictated by domain policies (fig1)

 

fig1

 

The default group of "Domain Users" will be added to this user (fig2). Since the user will never actually physically log in to any machines this can be removed, but you will need to have another group created (perhaps with no login control) since all users require a primary group. In this instance we will leave it as a member of "Domain Users". Normally no other permissions are needed. You may need to add some other permissions for this user depending how the AD & KDC are configured, we'll cover this at a later on in the troubleshooting section.

 

Fig2

 

The next step is to create the HTTP service class and map it to our user.

 

The HTTP service class

The HTTP service class differs from the HTTP protocol. Both the HTTP protocol and the HTTPS protocol use the HTTP service class. The service class is the string that identifies the general class of service. Well-known service class names include "www" for a Web service and "ldap" for a directory service. Generally, the service class name can be any string that is unique to the service class. Be aware that the SPN syntax uses a forward slash character  to separate elements. Therefore, the forward slash character  cannot appear in a service class name.

 

To map the service (which in this case will be used by our RSSO server) we'll need to run the "setspn" command from the KDC server command line, with the following format

 

setspn -S HTTP/severFQDN USER

 

-S : add arbitrary SPN after verifying no duplicates exist

HTTP/ : Service Class

ServerFQDN : The computer that is going to be using this service or the LB FQDN

USER : The user that we want to map the service to

 

So in our example we will run the following setspn command

 

setspn -S HTTP/rssolb.bmc.com MYRSSOPRINCIPLE  (fig3)  So this command is saying map the HTTP service class, for use by rssolb.bmc.com to my user called MYRSSOPRINCIPLE, but before doing this check that there is no other service called rssolb.bmc.com mapped to any other user. If running in an LB environment as in our case, there is no need to also map the individual server names since everything will be going through the load balancer, but in some instances depending how the the KDC is configured you may need to do this, we'll cover what log messages to look at when this is needed in the troubleshooting steps below. If you do need to do this then add the invidividual severs in the same way as before by running the setspn -S command, doing this won't cause any issues even if you don't need it. Run the following command to add the individual servers

 

setspn -S HTTP/rssoserver1.bmc.com MYRSSOPRINCIPLE

setspn -S HTTP/rssoserver2.bmc.com MYRSSOPRINCIPLE

 

So now we will have three services mapped to our user called MYRSSOPRINCIPLE

 

 

Running the setspn command in this case has thrown a "duplicate SPN found, aborting operation!" message Fig(3)  . This often occurs especially when a Managed Service Account has already been created and the service mapped

 

fig3

We can see above that we can't map our service to our user MYRSSOPRINCIPLE because this service is has already been mapped/registered with another user called "RSSOPRINCIPLE"

as we want to use the user "MYRSSOPRINCIPLE" we will need to delete/unregister the service to the user, to do this we'll need to run setspn with the  -D parameter (fig4). Sometimes you will see that there are multiple users that this services is registered to, this should not happen but it does and will need to be deleted.

 

setspn -D HTTP/rssolb.bmc.com RSSOPRINCIPLE

 

fig4

Once the delete command has been run, we can continue to map the service with our use again and should not get the duplicate SPN message (fig5)

 

setspn -S HTTP/rssolb.bmc.com MYRSSOPRINCIPLE  For completeness we've also added the individual server names (rssosever1.bmc.com & rssoserver2.bmc.com)

 

Fig5

 

You can view the registered service by using setspn with the -L parameter (fig6)

 

Fig6

 

Now we have our SPN created and services mapped. Normally this is enough and you would then continue to configure on the RSSO admin console. On the RSSO admin console there are two options to have RSSO connect to the KDC with the service principle user. One method is password, if the KDC allows SPN accounts to connect with a username and password then we are pretty much done. The second option on the RSSO admin console is to use a keytab file. A keytab file is generally for SSO when the KDC denies direct login with username and password. The keytab is a file containing pairs of Kerberos principals and encrypted keys. You will still need to run create the user and run the setspn command above before creating the keytab file.

 

Createing A Keytab File

This is an domain administrator function and these instructions should be action by the domain administrator, along with the create user and setpn commands above.

 

Open a command prompt and run the following command to create the keytab file

 

 

ktpass -out <outfile> -mapuser <PRINCIPLEUSER>  -princ <servicename> -pass PasswordOfMappedUser -ptype KRB5_NT_PRINCIPAL -crypto <cryptography type>

 

-out theoutput : file, the path and filename of the keytab file you want created

-mapuser :  The username you want to map the service to

-princ : The service class name

-password: password of the mapped user

-ptype:  Specifies the principal type.Type include

              KRB5_NT_PRINCIPAL is the general principal type (recommended).

                   KRB5_NT_SRV_INST is the user service instance.

                   KRB5_NT_SRV_HST is the host service instance.

 

-crypto: cryptography type to be used. Includes

              DES-CBC-CRC is used for compatibility.

               DES-CBC-MD5 adheres more closely to the MIT implementation and is used for compatibility.

               RC4-HMAC-NT employs 128-bit encryption.

               AES256-SHA1 employs AES256-CTS-HMAC-SHA1-96 encryption.

               AES128-SHA1 employs AES128-CTS-HMAC-SHA1-96 encryption.

               All states that all supported cryptographic types can be used. Note: The default settings are based on older MIT versions. Therefore, /crypto should always be specified.

 

In our case we are going to run the following ktpass command

 

ktpass -out c:\rssokeytab -mapuser MYRSSOPRINCIPLE -princ HTTP/rssolb.bmc.com@diffdom.com -pass Secret&c0mplex -ptype KRB5_NT_PRINCIPAL  -crypto all

The command will do the following:  map MYRSSOPRINCIPLE user to a service called HTTP/rssolb.bmc.com served by domain diff.com with a principle type of KRB5_NT_PRINCIPLE with all available cryptography and create the keytab file called c:\rssokeytab  (fig7)

 

fig7

 

Some issues that might occur when running the keytab command is using complex passwords with the username, the solution try a simpler password. When pasting the command from

a text editor some unseen characters might be pasted, this will make the keytab command fail, the solution is to type it directly into the the command prompt.

 

Once the keytab command is run successfully, two things will happen 1. The keytab file will be created in the path and name specified (fig8).

 

fig8

2. When viewing the user properties account details you will see instead of the userID the service name (fig9) take a note of the User Logon name and and the @ domain portion you will need this later on in RSSO configuration (in the same format)

 

fig9

 

The next step is to configure RSSO. If you created a keytab file copy it to the rsso sever if in an LB environment copy it to all RSSO servers.

 

Configuring Kerberos on the RSSO Admin Console

 

On the RSSO admin console, go to realm --->Add Realm and select Kerberos from the dropdown list and fill in the information.

 

KDC Server: The KDC server name where procedures above was carried out on. If in a KDC farm, first use the actual KDC server name. Do the test of successful try with the KDC farn name

                      Sometimes it takes a while for all KDC's to sync

Service Principle Name: Either the user name created for RSSO SPN or the service name if using keytab file

Kerberos Realm: The domain the KDC is on, if using password you will need to fill this in, if using keytab file it will be filled in automatically

SPN Password: If not using keytab file enter the password of SPN user created. If using keytab file this option is greyed out

UserID format: The format the username will be in when RSSO send the token and userID to the calling application for example in AR server the user can exists as JCKERDIFF and not                                    DIFFDOM/JCKERDIFF

 

User ID transformation: If the KDC/AD send the username to RSSO in a particular format, use this option to change the user format to work with the calling application

 

After filling in the information click the "Test" button if successful you will see a "Kerberos Connection Successful" message, if it fails review the troubleshooting portion below.

 

Configuring with password (fig10)

 

 

Configuring with Keytab file (fig11)

After the successful test, save the configuration.

 

Testing Kerberos Login

You will to make sure web browsers are configured to use kerberos. Generally this is done by group policies and is not changable, but if you are testing you should be able to change the web browser configuration.

 

Configuring Internet Explorer

Navigate to Tools > Internet Options > Advanced.

On the Advanced tab and in the Security section, select Enable Integrated Windows Authentication (requires restart).

On the Security tab, select Local Intranet.

Click Custom Level.

In the User Authentication/Logon section, select Automatic logon only in Intranet zone.

Click OK.

Click Sites and select all check boxes.

Click Advanced and add the Remedy SSO service website to the local zone (the website might be already added). For example, sample.bmc.com.

Click Add.

Click OK for all pop-ups.

 

Configuring Mozilla Firefox

Enter the following URL: about:config.

Click I'll be careful, I promise!

Double-click the Preference Name: network.negotiate-auth.trusted-uris.

Add the Fully Qualified Domain Name (FQDN) of the host, for example, sample.bmc.com.

Double-click the Preference Name:  network.automatic-ntlm-auth.trusted-uris.

Add the fully qualified domain name (FQDN) of the host, for example, sample.bmc.com.

Click OK.

 

Configuring Chrome: Chrome will piggy back the setting from internet explorer, so configure IE on the PC.

 

When the browser configuration is done, test the login.

 

Troubleshooting Kerberos

There a a few things that can error out when configuring kerberos for Authentication. The troubleshoot these review the following docs url Troubleshooting authentication issues  We'll cover some further troubleshooting in this post, this troubleshooting section will be updated as and when new issues are found.

 

When pressing the Testing Tab On the RSSO console we get a failure to connect to the KDC

The first place to look at when this issue occurs is the RSSO server logs. Set the RSSO server to "Debug" mode got to General--->Basic setting and set "Server Log Level" to "DEBUG" wait for about 15 seconds, reproduce the problem. Then take a look at the RSSO server log on the RSSO server in tomcat/logs/rsso.0.log

 

In each of these section, we'll take a look at what a good log should look like first we can use that as a baseline to compare with a log that shows errors.

 

Pressing the "TEST" button on the RSSO admin console and getting a "Connect to KDC Successful" message

 

28 Feb 2018 23:41:51.454 INFO Thread_41 com.bmc.rsso.core.kerberos.KerberosHelper.testServiceLogin(): Checking Kerberos service login ...

28 Feb 2018 23:41:51.454 INFO Thread_41 com.bmc.rsso.core.kerberos.KerberosHelper.getSubject(): Getting Kerberos subject ...

.

28 Feb 2018 23:41:51.459 INFO Thread_41 com.bmc.rsso.core.kerberos.KerberosHelper.getSubject(): Starting login context, KDC:clm-aus-021891.diffdom.com, realm:DIFFDOM.COM, user:MYRSSOPRINCIPLE, initiator:true

.

.

28 Feb 2018 23:41:52.140 DEBUG Thread_41 com.bmc.rsso.core.kerberos.KerberosHelper.logSubject(): Kerberos subject obtained: Subject:

Principal: MYRSSOPRINCIPLE@DIFFDOM.COM

Private Credential: Ticket (hex) =

0000: 61 82 04 48 30 82 04 44   A0 03 02 01 05 A1 0D 1B  a..H0..D........

 

The above log shows successful connection to the KDC server from RSSO using the SPN user (MYRSSOPRINCIPLE) and shows the HEX value of the ticket the principle gets from the KDC

 

 

28 Feb 2018 23:45:34.330 INFO Thread_43 com.bmc.rsso.core.kerberos.KerberosHelper.getSubject(): Starting login context, KDC:clm-aus-021891.diffdom.com, realm:DIFFDOM.COM, user:MYRSSOPRINCIPLE, initiator:true

28 Feb 2018 23:45:34.330 INFO Thread_43 com.bmc.rsso.core.kerberos.KerberosHelper.getSubject(): Login using password

28 Feb 2018 23:45:34.360 SEVERE Thread_43 com.bmc.rsso.core.kerberos.KerberosHelper.testServiceLogin(): Could not obtain Kerberos subject

Details: Pre-authentication information was invalid (24)

 

The above shows a failed connection to the KDC in this instance the SPN password has been changed but not updated on the RSSO admin console The RSSO admin console will give you a message also saying this "Invalid SPN password. Check if SPN account password has been changed". However you might also see the message when

 

1. The SPN user is found on the KDC and the password is correct, but the KDC does not allow the connection

2. When specific user permissions are needed for the SPN user to connect to the KDC

 

In which case the above two point will need to be checked on the KDC side. You will need to speak to the doman admin to take a look at the windows event logs for kerberos messages.

By default kerberos related messages are not logged in windows event viewer it will need to specifically be enabled. This will need a registry change

 

Enabling Kerberos Event Logging on a Specific Computer

  1. Start Registry Editor.
  2. Add the following registry value:
    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\Parameters
    Registry Value: LogLevel
    Value Type: REG_DWORD
    Value Data: 0x1

    If the Parameters subkey does not exist, create it.

    Note Remove this registry value when it is no longer needed so that performance is not degraded on the computer. Also, you can remove this registry value to disable Kerberos event logging on a specific computer.
  3. Quit Registry Editor. The setting will become effective immediately on Windows Server 2003 and newer, and on Windows XP and newer. For Windows 2000, you must restart the computer.
  4. You can find any Kerberos-related events in the System & Security log.

 

Don't forget to remove this registry entry when done troubleshooting. See How to enable Kerberos event logging

 

 

When  trying to  run the KTpass command we get a message "KTPASS Getting error "Failed to retrieve user info for <UserName>: 0x5"

This is a KDC configuration issue. Running the following on the KDC powershell resolves this issue "add-kdsrootkey -EffectiveTime (Get-Date).AddHours(-10)" see Add-KdsRootKey

 

When logging into an application i.e. Midtier, MyIT  ADDM we get a pop-up prompting for username and password. This is either due to either the browser not configured correctly (see above) or the domain you are login in from is not the same domain as the users domain, or an issue with the application or the agent on the application. If the userID is seen in the RSSO user sessions list, this generally means the kerberos Authentication has been done, the next troubleshooting steps should be done on the application side. Check the application log and the rssoagent log found in tomcat/logs directory.

 

The tomcatX-stdout.<date>.log file on the RSSO server also provides useful information when troubleshooting kerberos, include this file in the troubleshooting log review. Messages like the below are logged in this file.

 

>>> KdcAccessibility: remove clm-aus-021891.diffdom.com

>>> KDCRep: init() encoding tag is 126 req type is 11

>>>KRBError:

sTime is Thu Mar 01 00:00:36 GMT 2018 1519862436000

suSec is 121556

error code is 25

error Message is Additional pre-authentication required

sname is krbtgt/DIFFDOM.COM@DIFFDOM.COM

eData provided.

msgType is 30

 

We can see the SPN ticket in the rssoserver log, but users are not able to login. Use the klist command from the command prompt and see if a user can request a ticket directly from the KDC outside of RSSO see Klist

 

Share:|

In this post we'll take a look at locking down Tomcat Web Server. We'll be specifically looking at locking down the Tomcat that runs the RSSO server application, some of these configurations can also be used to configure other applications that run on Tomcat Web Server such as Remedy Midtier.

 

BMC Software is engaged in an ongoing process to continually improve the security of the applications it develops. If you have encounter any security issues with BMC products the first thing to do is to contact the BMC Appication Security team. DO NOT disclose any suspected vulnerabilities publicly. For information on how to contact the BMC Application Security team see https://www.bmc.com/corporate/bmc-security.html

 

Report any suspected Vulnerabilities of Tomcat Webserver to Apache see https://httpd.apache.org/security_report.html

 

This is a collaborate post between BMC Support, Engineering/Dev , Apps Security team and Customers. So we'll encourage you to post comments, questions and suggestions you may have, make them public if possible so everyone can benefit from your experiences (Do Not Disclose any unknown or suspected vulnerabilities publicly see above on how to contact the BMC Application Security team).

 

Locking down the Tomcat Server is only one of your security measures along with securing the network and all assets within it.  The security of the system will only be as secure as the weakest link in the environment and your applications as secure as the container that hosts it (Tomcat).

 

To start off with the first thing you will need to do is use the latest supported version of Tomcat (at the writing of this post Tomcat 8) see the following post Migrating Remedy Single Sign-On To A New Version Of Tomcat for information on migrating to the latest version and also the BMC Compatability matrix for information on which versions are supported. Along with TC its a good idea to also update to the latest supported level of java.

 

Versions Used in the examples in this post

Remedy Single Sign-On 9.1.04

Apache Tomcat 8.5.23

Java JRE 8.0_151

 

Apache provides a report of which security  has been fixed in each version it releases go to Apache Tomcat® - Reporting Security Problems to see what has been found and fixed in each version. Another good resource from Apache is Apache Tomcat 8 (8.0.48) - Security Considerations some of the information from that doc page we'll cover in this post along with RSSO specific information.

 

Locking down a TC server is a balancing act, we don't won't to overdo the securing to a point where users experience a slowdown in performance or not able to access the applications altogether. This portion is going to be determined by many factors, mainly to do with a particular environment, what works well for one environment will not necessarily work for another, there are too many factors which dictates this that it would be impossible for a one rule suites all configuration, so its important when making these changes that they are tested before making them in a live production system.

 

Tomcat Out Of the Box

By default tomcat can be installed and configured very quickly to start publishing web applications. The default install can and should be made more secure, if the TC server is accessible over the web this is more imperative. The default tomcat is configured in none SSL mode (HTTP) and also deploys its standard applications, An attacker could use these applications to gain access to other portions of the system.

 

We'll start by removing these default applications and get TC into secure SSL mode.

 

Tomcat Default Applications

By default TC deploys the following applications Docs, Examples, Host-manager, Manager, ROOT. All these applications serves some purposes for TC, but we won't need them for running RSSO. A brief summary of what these applications are and why they can be removed.

 

ROOT - This is the deault TC application when going to http://severname:8080, this will show the tomcat "is running" page along with the version of Apache Tomcat being used. For RSSO we won't need this page to do any configuration, you can change the default web page to something custom to your environment either a disclaimer or even just a blank page, This should be deleted.

 

Examples - Apache recommends removing these applications, these example applications can be used to gather more information  about the system and other applications. This should be deleted

 

Host Manager - This application is not accessible by default to anyone, unless you are creating an virtual hosts on this TC server you generally won't ever need to use this, certainly not to get RSSO configured. If you do intend to use this see Apache Documentation to secure this application.  This should be deleted.

 

Manager - This is used to allow remote deployment of web applications, its frequently used by attackers to gain information and access to the system. If there is a need to do remote deployment of applications then make sure you secure this application by following guidance from Apache on the docs page, for RSSO we don't need this. This should be deleted

 

Docs - Holds the doc pages of Apache and also hold version information. You can get the latest docs information at https://tomcat.apache.org so we really don't need this. This can be deleted

 

If deleting or removing these applications is not possible for some reason, then move them into another location on the system away from the publishing area in TC /webapps. After moving or deleting the the default applications restart Tomcat to make sure it comes up correctly, with no errors in the apache-tomcat8.5.23\logs\catalina.log file. Going to any page on on the TC server should return a "Page can't be found HTTP ERROR 404" or a custom message. You should not redirect the default page to the RSSO admin console by default.

 

SSL Mode

The advantages of using SSL has long been documented and should be one of the first things you do when installing TC in a secure configuration. SSL certificates are used to protect sensitive information as it crosses notworks by way of encryption and provides a framework of Trusted and Trustees.  SSL is configured by enabling in the tomcat /conf/server.xml file. We'll take a look at some of these entries to enable SSL for TC in the server.xml file.

 

By default tomcat is installed in HTTP mode deafult port 8080. To enable SSL mode we need to add the correct entries in the server.xml file.

 

The format of the connector port in server.xml will look something like the below

 

<Connector port="8080" protocol="HTTP/1.1"

               connectionTimeout="20000"

               redirectPort="https_port" />

 

   <Connector port="<https_port>"

                      protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"

                       maxThreads="150" scheme="https" secure="true"

                       maxHttpHeaderSize="32768"

                       clientAuth="want"

                       sslEnabledProtocols="TLSv1.1, TLSv1.2"

                       ciphers= "<list of ciphers to use> "

              keystoreFile="<path to keystore location>"

                      keystorePass="<keystore password>"

                      keyAlias="<key alias name in the keystore>"

                      truststoreFile="<trusstore location optional>"

                      truststorePass="<truststore password" />

 

The above entries need to be in the server.xml file to enable SSL mode. See Creating a keystore From Tomcat Webserver Video for instructions on how to create thge keystore, sign the request and import the certificate onto the tomcat web server (Video shows the TSPS tomcat server, but is valid for RSSO tomcat web server also)

 

SSL Offloading

The best way to manage SSL certificates in the environment is to use SSL Offloading. SSL Offloading/Termination allows the Load Balancer to deal with any certificates exchanges on behalf of the server and client.  See Remedy SSO Managing SSL Certificates with SSL Offloading video for more information and configuration.

 

Redirects & HTTPS Only

In some instances you may not want the port of the Tomcat server to be published along with the URL. The best method to do this is to have a Load Balancer rewrite the url and remove the port from the url. If you don't have or use a Load Balancer you will have to make some to the tomcat server.xml & web.xml files. You may also want to only allow HTTPS connections, again this best done at the Load Balancer, but it can also be achieved using Tomcat's configuration files.  The configurations below uses Tomcat auto redirect ports (80 & 443), which have the affect of removing the ports from the URL, this is done in the server.xml file

 

in the server.xml file change the Connector port to 80, redirect port to 443 & HTTPS connector port to 443

 

<Connector port="80" protocol="HTTP/1.1"

               connectionTimeout="20000"

               redirectPort="443" />    

 

    <Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"            

                       maxThreads="150" scheme="https" secure="true"

                       maxHttpHeaderSize="32768"

                       clientAuth="want"

                      sslEnabledProtocols="TLSv1.1, TLSv1.2"

                       ciphers="HIGH:!aNULL:!RC4:!MD5:@STRENGTH"

              keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat8.5.23/conf/keystore.p12"

                      keystorePass="internal4bmc"

                      keyAlias="tomcat"

                      truststoreFile="C:\Program Files\Apache Software Foundation RSSO\apache-tomcat8.5.23\conf\TrustStore.jks"

      truststorePass="internal4bmc"

      />

 

Ciphers: Usually there is a long list of ciphers you can list to be available (The first acceptable cipher found will the one used)

ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA........."

 

Tomcat also accept OpenSSL syntax for the list for ciphers e.g ciphers="HIGH:!aNULL:!RC4:!MD5:@STRENGTH" as above. By not naming ciphers explicitly this makes it easier to use stronger ones automatically as new Tomcat & Java versions are released.

 

HTTPS Only &  HTTP Strict Transport Security (HSTS)

To have the TC server to only accept HTTPS secure connections put the following in the web.xml file (only use when communicating withe the server directly, if using an LB or a reverse proxy have the LB or proxy do the HTTP/HTTPS conversion)

 

<!-- Force HTTPS, required for HTTP redirect! -->

   <security-constraint>

   <web-resource-collection>

   <web-resource-name>Protected Context</web-resource-name>

   <url-pattern>/*</url-pattern>

   </web-resource-collection>

    

   <!-- auth-constraint goes here if you require authentication -->

   <user-data-constraint>

   <transport-guarantee>CONFIDENTIAL</transport-guarantee>

   </user-data-constraint>

</security-constraint>

 

The configurations above will take effect once the TC service is restarted. Now if you go to http://rssoserver.bmc.com/rsso it will redirect to HTTPS://rssoserver.bmc.com/rsso/admin/#/

 

NOTE: Check that no other process is using port "80" on the system run "netstat -ano" to see if the port is opened and used by another process.

 

HSTS

If a website is accessed through HTTP and there is a redirect to HTTPS, this creates an opportunity for a man in the middle attack, the redirect (HTTP) can be used to redirect to a malicious site. The HTTP Strict Transport Security header informs the browser that it should never load a site using HTTP and should automatically convert all attempts to access the site using HTTP to HTTPS requests instead. To configure HSTS edit the /tomcat/conf/web.xml file, uncomment the httpHeaderSecurity filter definition and add the hstsMaxAgeSeconds & hstsIncludeSubDomains parameters

 

<filter>
  <filter-name>HTTP Header Security Filter</filter-name>
  <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
  <init-param>
  <param-name>hstsMaxAgeSeconds</param-name>
  <param-value>31536000</param-value>
  </init-param>
  <init-param>
  <param-name>hstsIncludeSubDomains</param-name>
  <param-value>true</param-value>
  </init-param>
</filter>
<filter-mapping>
  <filter-name>HTTP Header Security Filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

 

See the HTSTS Parameters for information of available parameters.

 

 

Tomcat User for service/Process

Running the Tomcat Service/Process as a privileged user should be avoided i.e. any user that has Administrator or Root permissions. Create a dedicated user to start the Tomcat service/process.

 

Windows

Create a user with "Log on as service". On the file system set the following permissions on the Tomcat Directory for the user "Modify", "Read & Excute", "List Folder Content", "Read" and "Write" (Fig1)

 

Fig1.

 

Linux

For security purposes, you need to create a dedicated non-root user "tomcat" who belongs to the "tomcat" group. From the shell:

sudo groupadd tomcat

sudo mkdir /opt/tomcat
sudo useradd -s /bin/nologin -g tomcat -d /opt/tomcat tomcat

 

This creates a user "tomcat" who belongs to the group "tomcat". You cannot use this user account to log into the system. The home directory is /opt/tomcat, which is where the Apache Tomcat program will reside (change the location to where you want to install Tomcat)

 

 

Tomcat Auto Deploy Feature

One feature Tomcat has out of the box is the ability to deploy .war files on startup. This should be disabled. Not only will this stop unauthorised applications from deploying it will also make startup quicker.  If you are using Tomcat as a shared web Server , ensure that no other applications needs this auto deployment feature. Auto deployment can be turned off in the server.xml file

 

<Host name="localhost"  appBase="webapps"

            unpackWARs="true" autoDeploy="false">

 

 

Tomcat Shutdown Port

Disable the tomcat shutdown port by setting the shutdown port value to "-1" in the server.xml file . This prevents malicious actors from shutting down Tomcat's web services.  If the port can not be disabled then set a strong password for shutdown. You can still shutdown tomcat directly on the server itself with the "-1" entry but not remotely with something like telnet

 

e.g. Disable port

<Server port="-1" shutdown="SHUTDOWN">

 

e.g. Strong Password

<Server port="8005" shutdown="5hu!dOwN!\">

 

Connectors

By default Tomcat publishes two connector types HTTP & AJP

 

non-SSL/TLS HTTP/1.1 8080

AJP xx Connector 8009

 

In most configurations Tomcat request/responses will go over HTTP/HTTPS.  The AJP connector is generally used for parsing requests through reverse proxies, although still slightly more efficient than HTTP over reverse proxies it's often not needed and should be disabled in the server.xml file (though test that connections still work if you are using a reverse proxy)

 

From

 

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

 

To

 

<!-- <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> -->

 

 

Clear Text Password In Server.xml file

Clear text passwords is never a good idea. In Tomcat Because there is no good way to "secure" them. When Tomcat needs to connect to a database, it needs the original password. While the password could be encoded, there still needs to be a mechanism to decode it. And since the source to Tomcat is freely available, the attacker would know the decoding method. So at best, the password is obscured see FAQ/Password - Tomcat Wiki

 

Ciphers

Its important not to specify any weak ciphers to be used in the server.xml file some ciphers along with SSL versions have been deemed not to be secure and should not be used.

 

SSL v2 is insecure and must not be used. This protocol version can be used to attack RSA keys and sites with the same name even if they are on an entirely different servers (the DROWN attack).

 

SSL v3 is insecure when used with HTTP (the POODLE attack) and weak when used with other protocols. It’s also obsolete and shouldn’t be used.

 

TLS v1.0 is a legacy protocol that shouldn't be used.

 

TLS v1.1 and v1.2 are both without known security issues, but only v1.2 provides modern cryptographic algorithms.

 

TLS v1.2 should be your main protocol because it's the only version that offers modern authenticated encryption (also known as AEAD)

 

Choosing which ciphers to use will depend on the requirements from the security team. You can use the below as a starting point

 

ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA"

 

The recommendation here though is to use the OpenSSL syntax for the list for ciphers e.g ciphers="HIGH:!aNULL:!RC4:!MD5:@STRENGTH". By not naming ciphers explicitly this makes it easier to use stronger ones automatically as new Tomcat & Java versions are released.

 

Which Ciphers gets used? By default Tomcat will use the first acceptable cipher presented by the client browser. But often this selection is not the strongest cipher available. This behavior can be changed by using useServerCipherSuitesOrder="true" in the server.xml file. By enabling useServerCipherSuitesOrder Tomcat will probe the client using this ordered sequence until a supported cipher is matched making sure the most secure connection available is always used.

 

NOTE: Always test your TLS configuration in a testing/dev/ environment, transferring the changes to the production environment only when certain that everything works as expected

 

 

Other Tomcat Configurations

Out of the Box the following tomcat parameters are disabled with Tomcat (version 8.0 ), its good to be aware of them in case you need to enable them for reasons of troubleshooting etc. be sure to disable them after. Most of these entries are configured in the server.xml file they are not there by default, you will have to specifically add them in.

 

allowTrace - The allowTrace attribute may be used to enable TRACE requests which can be useful for debugging. Due to the way some browsers handle the response from a TRACE request (which exposes the browser to an XSS attack), support for TRACE requests is disabled by default.

 

xpoweredBy  - The xpoweredBy attribute controls whether or not the X-Powered-By HTTP header is sent with each request. If sent, the value of the header contains the Servlet and JSP specification versions, the full Tomcat version (e.g. Apache Tomcat/8.0), the name of the JVM vendor and the version of the JVM. This header is disabled by default. This header can provide useful information to both legitimate clients and attackers.

 

SSL V2,V3 - SSLv2 and SSLv3 are inherently unsafe (Poodle Attack), there is no reason to have this protocol enabled. Search the server.xml file for enabled protocols "sslProtocol=" and remove it from the protocol list

 

deployXML - In a hosted environment where web applications may not be trusted, set the deployXML attribute to false to ignore any context.xml packaged with the web application that may try to assign increased privileges to the web application. Note that if the security manager is enabled that the deployXML attribute will default to false.

 

Listings - The DefaultServlet is configured with listings set to false. This isn't because allowing directory listings is considered unsafe but because generating listings of directories with thousands of files can consume significant CPU leading to a DOS attack.

 

DefaultServlet - This applies to the default conf/web.xml file and WEB-INF/web.xml files in web applications if they define the components mentioned here.

The DefaultServlet is configured with readonly set to true. Changing this to false allows clients to delete or modify static resources on the server and to upload new resources. This should not normally be changed without requiring authentication.The DefaultServlet is configured with listings set to false. This isn't because allowing directory listings is considered unsafe but because generating listings of directories with thousands of files can consume significant CPU leading to a DOS attack. The DefaultServlet is configured with showServerInfo set to true. When the directory listings is enabled the Tomcat version number is included in the response sent to clients. To avoid this, you can explicitly configure a DefaultServlet and set its showServerInfo attribute to false.

 

Host Header Attack

A Host Header Attack is a common way for an attacker to manipulate the host header to launch a Web-Cache Poisoning or a Password Reset Poisoning attack. Host header attack vulnerability have been identified an fixed in version of Tocat 8.x see Apache Tomcat 8.x vulnerabilities

 

Java Security

Always use the later version of Java with Tomcat and ensure your applications supports the new version of Java version, for information on the supported version of Java for RSSO see the BMC Compatibilty Matrix To configure the security settings for Java open the java control panel-->Security tab and set the security level

 

Java 8u20 control panel Security tab

 

Security levels in the Java Control Panel

 

Very High

This is the most restrictive security level setting. All the applications that are signed with a valid certificate and include the Permissions attribute in the manifest for the main JAR file are allowed to run with security prompts. All other applications are blocked.

 

High

This is the minimum recommended (and default) security level setting. Applications that are signed with a valid or expired certificate and include the Permissions attribute in the manifest for the main JAR file are allowed to run with security prompts. Applications are also allowed to run with security prompts when the revocation status of the certificate cannot be checked. All other applications are blocked.

 

Medium (removed from Java 8 Update 20 and later versions)

Only unsigned applications that request all permissions are blocked. All other applications are allowed to run with security prompts. Selecting the Medium security level is not recommended and will make your computer more vulnerable should you run a malicious application.

 

Java JCE (Java Cryptography Extension) Unlimited Strength

Its advisable to install Java unlimited strength policy files. Java run time environment out of the box enforces a limitation on certain key length parameters the length is limited to 128 bits. To use a key length higher that 128 bits (192 or 256 bits) you will need to download and install the JCE unlimited strength policy files. Download the unlimited strength files for your version of java from Oracle Java Download site.

 

NOTE:  From Java 8 u162 the unlimited policy is enabled by default. You no longer need to install the policy file in the JRE or set the security property crypto.policy

Some countries restrict the use of encryption key lengths, check the local country laws.

 

 

Application Security

Each application on the TC webserver has its own Deployment Descriptor file (web.xml) which normally will be in /webapps/application_name/WEB-INF. The configuration discussed above is the general configuration for TC, if there are multiple applications on the TC server, each application can be configured individually using its own web.xml file. Its best to make configuration changes globally and then if a specific configuration is needed for a particular application then make the changes to its web.xml file.

 

Remedy Single Sign-On

RSSO provides the function to use secure cookies. If you are using HTTPS  only then there is really no need to set this flag (doing so won't cause any issues) since all the trafffic from the server to the client will be encrypted. However if the tomcat is also configured to use HTTP then that can pose a security risk of cookies being intercepted and used in an impersonation attack.  We can use a secure flag for cookies even if HTTP is being used on the server, this will encrypt the cookie. The option to enable secured cookie in RSSO (fig1). If this option is selected then all applications must also run on HTTPS and the application servers must be accessed through HTTPS only. Otherwise, it causes a redirection loop.

 

Fig1

 

 

Limiting access to the RSSO Admin Console

You should limit access to the RSSO admin console to either a single IP address or a subset of IP address. Use the Remote Address filter in tomcat's server.xml file  to configure this, this is especially necessary if you are exposing the apps over the internet.

 

<filter>

    <filter-name>Remote Address Filter</filter-name>

    <filter-class>org.apache.catalina.filters.RemoteAddrFilter</filter-class>

    <init-param>

        <param-name>allow</param-name> <!-- or deny -->

        <param-value>IPADDRESSESofAllowedServers</param-value> <!-- regexp for your ip addresses -->

    </init-param>

</filter>

<filter-mapping>

    <filter-name>Remote Address Filter</filter-name>

    <url-pattern>/admin/*</url-pattern> <!-- the url of your admin page or login page, etc -->

</filter-mapping>

 

(IPV6 environments)

<filter>

   <filter-name>Remote Address Filter</filter-name>

   <filter-class>org.apache.catalina.filters.RemoteAddrFilter</filter-class>

   <init-param>

   <param-name>allow</param-name> <!-- or deny -->

   <param-value>10\.10\.1[12]\..*</param-value> <!-- regexp for your ip addresses -->

   </init-param>

</filter>

<filter-mapping>

   <filter-name>Remote Address Filter</filter-name>

   <url-pattern>*/admin</url-pattern> <!-- the url of your admin page or login page, etc -->

</filter-mapping>

 

 

Scanning For Vulnerabilities

After going through the TC & RSSO hardening before, ask the Network/Security team to run a vulnerability.  The scan will provide a detailed report of any vulnerabilities identified on the system, check the report and follow the recommendations of the report.

 

Reporting Vulnerabilities

BMC Software is engaged in an ongoing process to continually improve the security of the applications it develops. If you have encounter any issues with BMC products the first thing to do is to contact the BMC Appication Security team. DO NOT disclose any suspected vulnerabilities. For information on how to contact the BMC Application Security team see https://www.bmc.com/corporate/bmc-security.html

 

Report any suspected vulnerability to Apache see https://httpd.apache.org/security_report.html

Share:|

In this post we'll take a look at how to migrate the RSSO application to a new version of tomcat web server. There are many reasons why you might want to migrate to a new tomcat version, some of which can include:

 

  • Keeping up with the latest supported version of Tomcat
  • A newer version has the features you require
  • New Tomcat support for the latest version of java
  • The need for better web server performance

 

In this blog we'll use the example of migrating the RSSO application from tomcat 7.0.62 to apache-tomcat8.5.23. We will be installing the new version of Tomcat and Java on the same machine as the 7.0.62 Tomcat install to minimise downtime.

 

File System locations used in this example:

 

Tomcat 7 : C:\Program Files\Apache Software Foundation RSSO\apache-tomcat-7.0.62

Tomcat 8 : C:\Program Files\Apache Software Foundation RSSO\apache-tomcat8.5.23 (will be installed in this path)

Java 7 : C:\Program Files\Java\jre7

Java 8 : C:\Program Files\Java\jre1.8.0_151  (will be installed in this path)

 

This procedure will be done on Windows but the process will still be valid on Linux, unless stated for Windows only.

 

Installing The New Version of Tomcat(for this post apache-tomcat8.5.23 & Java jre1.8.0_151)

 

1. Download the latest version of Tomcat from https://tomcat.apache.org/ & Java Check the BMC compatibility matrix for the version of RSSO you are running.

 

2. Install java. NOTE: If installing Java on the same server as a previous install of Tomcat, Java installer will asks to uninstall previous versions of java select "No". This is until we confirm that the new version of Tomcat is working as expected.

 

3. Extract the downloaded Tomcat files to the Apache Software directory i.e. "C:\Program files\ApacheSoftware" or "\opt\ApacheSoftware" or where ever you have a previous version of TC

 

4. Open a command prompt and set environment variable JAVA_HOME to the new version of tomcat. We will set the Java environment variable permanently at a later point once we have confirmed everything is working. Keep this command prompt open.

 

5. From command prompt run the following command and confirm the correct version of java is running "Java -version"

 

6. On windows we need to create the service for Tomcat. Open command prompt "cd" in to the the Apache/tomcat/bin directory and run "service.bat install" command. Once the service has been created successfully (fig1) check in windows services manger for the service.

 

fig1

If you have a previous version of Tomcat running on the server leave it running for the time being and do no start the new Tomcat service just yet.

 

 

Moving the RSSO Installation Files

We now have to move the RSSO application files from the previous install of Tomcat to the new one.

 

1. Copy the "/Tomcat/webapps/rsso" directory from the previous Tomcat install to the same location on the new Tomcat install. In the example we are using from

"C:\Program Files\Apache Software Foundation RSSO\apache-tomcat-7.0.62\webapps" to "C:\Program Files\Apache Software Foundation RSSO\apache-tomcat8.5.23\webapps"

 

2. Copy the following files from the old version of Tomcat from tomcat/lib to the same location on the new version. Note if you have installed a future version of RSSO relative to this blog date the versions numbers may have changed.

 

ojdbc6-11.2.0.2.0.jar

postgresql-9.4.1207.jre7.jar

sqljdbc4-4.0.jar

hsqldb-2.3.5.jar

 

3. If you have a trust store location used by RSSO SAML Authentiction, login to the RSSO Admin console --->Advanced and check where the trust/keystore store path is. You will then need to copy this file from the the old version of Tomact to the same location on the new install (fig2)

 

fig2 Shows the location of the store usually used for SAML authentication (field names may have changed from one version of RSSO to another) just copy the file to the new Tomcat location if its not a common path as show below

 

Moving Tomcat files & Edit Configuration File

Our next steps is to move any tomcat configuration files from the previous version to the next version & also make some changes to the server.xml file if using HTTPS

 

1. If the previous Tomcat version was running on HTTPS we need to move over, the keystore file and trustore files files (If being used) RSSO

Open the Tomcat\conf\server.xml file, search for " keystoreFile" This will give you the location of the keystore and truststore (if being used)

copy the keystore file from the previous version of tomcat to the same location on the new Tomacat server. If the path is common to both versions of tomacat it does not need to be copied for example if the keystore path is "C:\mykeystores\keystore.p12" then there is no need to move it.

 

2. If you have made any customisation to the /tomcat/conf/context.xml file then copy this file to the new Tomcat Install in the same location

 

3. If using HTTPS our next step is to copy the entries from the server.xml file from the old version of Tomcat to the new version. Open the tomcat/conf/server.xml file search for " keystoreFile" copy the whole segment from this connector port element and place it in the same location in the new Tomcat server.xml file and save the file. The segment will look like the example below

 

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"             

         maxThreads="150" scheme="https" secure="true"

         maxHttpHeaderSize="32768"

         clientAuth="false" sslProtocol="TLS"

ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA"                  

         keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-7.0.62/conf/keystore.p12"

         keystorePass="internal4bmc"

         keyAlias="tomcat"/>

 

NOTE: Remember if the keystore location is in the old Tomcat version path (highlighted in green) you will need to change it to point to the new version path as per example below

 

FROM:   keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-7.0.62/conf/keystore.p12"

TO:         keystoreFile="C:/Program Files/Apache Software Foundation RSSO/apache-tomcat-8.5.23/conf/keystore.p12"

 

 

Testing

At this point we have configured everything we need to start the new Tomcat service.

 

1. Stop the old tomcat service

2. Start the new tomcat service

3. Login to the RSSO admin console with the same URL as before

 

You should now be able to continue testing. Test for a few days to make sure everything is OK before moving on to finalising the install. If you are not able to login to the RSSOadmin console

stop the new tomcat service, restart the old one then check the troubleshooting section below

 

Finalising

If you have been testing for a few days and have not come across any issues with the new version of Tomcat you can proceed to finalise the install. To do this

 

Windows: Set System Variable JAVA_HOME and or JRE_HOME to the new version of Java (just be aware of any other applications using the old java version) there is no harm in not doing this as the Tomcat service will always use the new one if you ran the service.bat correctly above.

 

You can remove the Tomcat Service from windows by opening a command prompt "cd" in to the old version of Tomcat directory/bin and run "service.bat remove" (fig3)

 

fig3

 

You can then proceed to delete the old tomcat install files.

 

Linux: Set JAVA_HOME and OR JRE_HOME to the version of Java in the user profile. If you are not sure if other applications are using the old version of Java don't change it, just remember you might need to EXPORT JAVA_HOME=NewJavaPath when starting the the tomcat process. If you don't need the files from the old Tomcat version they can be deleted.

 

Troubleshooting

If after starting up the new Tomcat service and you are not able to log in yo the RSSO admin console, the first place to look is in the Tomcat/Logs/catalina.<date>.log file

check for any error messages. A common one from the procedure above would be

 

java.lang.IllegalArgumentException: Illegal character in path at index 12: C:/ProgramFiles/Apache Software Foundation RSSO/apache-tomcat-8.5.23/conf/keystore.p12

at java.net.URI.create(Unknown Source)

at java.net.URI.resolve(Unknown Source)

 

This message indicates that the path to the keystore file is not found. Confirm the path is correct

 

If there are not any errors in the catalina.log file, then the webserver itself has come up correctly. The next step is to look in the Tomcat/logs/rsso.log file for any errors, a common one

from the procedure above is

 

Details: Unable to load class: com.microsoft.sqlserver.jdbc.SQLServerDriver from ClassLoader:java.net.URLClassLoader@19469ea2;ClassLoader:ParallelWebappClassLoader

  context: rsso

  delegate: false

----------> Parent Classloader:

java.net.URLClassLoader@19469ea2

org.apache.naming.NamingContext.lookup(NamingContext.java:856)

 

This usually indicate some of the RSSO library files are missing from the Tomcat/lib directory, confirm you have copied the files from the previous version of Tomcat correctly, the files are

ojdbc6-11.2.0.2.0.jar

postgresql-9.4.1207.jre7.jar

sqljdbc4-4.0.jar

hsqldb-2.3.5.jar

Note if you have installed a future version of RSSO relative to this blog date the versions numbers may have changed.

 

If all these files are in the lib directory, look at the error message in the RSSO.log file, that will usually give you a hint about which lib file is missing, then check the previous version of Tomcat/lib directory for the file name and copy it over.

Share:|

The RSSO application needs to have its own database to function, some of the tables in this database will hold data for authentications such as SAML, LDAP and AR server as well as tables for user sessions and local internal users.

 

There are two ways to create the RSSO database

  • Let the installer create the database/tables (Preferred method)
  • Pre-Create the RSSO_USER user & database before running the installation

 

 

Letting the installer create the tables

 

Create New User Option

The preferred & quickest method of creating the database is to let the installer create the database, for this you will need a privileged account such as "sa" for MSSQL or "system" for Oracle

This account is only used during the installation and will not be required or used again. If possible during the user input portion of the installation ask the DBAs to enter in a privileged account user name & password if they can not share the account details with you (which is usually the case), so its best to have them at hand to enter in the database and password.  This is the fastest and most efficient way to run the RSSO installer. We need a privileged account to create the database, tables and the RSSO database user "RSSO_USER".

During the install you will be asked for the privileged account  when the "Create New User" option is selected (fig1)

 

Fig1. Showing Create new user (for Oracle)

 

Use Existing User Option

Another option you have is to ask the DBA to pre-create the "RSSO_USER" account in the database and use the "Use Existing User" option during the install.

 

For MSSQL: Ask the DBA to create the "RSSO_USER" user and the container database "rsso" its easier to create the container DB along with the user and make the "RSSO_USER" the owner of the "rsso" database, which in turn will give the user "dbo" access to the database (Schema) (fig2). The DBA will need to provide you with the user name, password and database name (in this case "rsso")

 

Fig2. Shows the RSSO_USER and the RSSO database configuration

 

For Oracle: Ask the DBA to create the "RSSO_USER" account in oracle with CONNECT & RESOURCE roles, "Unlimited Quota for the default user table space"  with "Password Expired" not selected (fig3). The DBA will need to provide you with the username, password, SID or Service Name, you will use this as the "SID" or "Service Name" during the install.

 

Fig3. Shows the user creation for the "RSSO_USER" in oracle along with the granted roles

 

After the RSSO_USER has been created, select the "Use Existing User" Option during the RSSO install. The installer will then create the tables for RSSO (fig4)

 

Fig4. Shows oracle used as the database and "Use Exiting User Option" selected for install

 

 

Pre-Creating User & Database Tables Before the Installer Runs

In some environments the only option available is to pre-create the database due to global policies. RSSO provides the files needed to create the database before running the installer. When the install run's it will connect to the DB for verification and only deploy the system files. The following procedure is a DBA function and these instructions should be sent to the DBA to action.

 

Summary of Steps

  • Copy the Disk1/lib/rsso-database-all.jar file from the installer into a temp directory on the local database
  • Create the RSSO database user
  • Create the database.properties file
  • Execute the rsso-database-all.jar file to create the database

 

NOTE: Its important the rsso-database-all.jar file is from the RSSO version you want to install and not from a previous version, so only use the file from the installer version you have downloaded and get the file from the installer, never use a rsso-database-all.jar that has been sent to you unless instructed to by BMC SUPPORT.

 

You will need java 7 and over to be able to complete this process successfully

 

The first thing we need to do is copy the Disk1/lib/rsso-database-all.jar and place it in a folder on the database. In the same folder create an empty file called "database.properties"

Open the "database.properties" file for edit

 

FOR MSSQL:

 

1. The first thing we need to do is create a database called "rsso" then run the following SQL to create te user and assign RSSO_USER as the DB owner. Change the password to meet your policy (highlighted in red)

 

CREATE LOGIN [RSSO_USER] WITH PASSWORD=N'RSSO#Admin#', DEFAULT_DATABASE=[rsso], DEFAULT_LANGUAGE=[us_english], CHECK_EXPIRATION=OFF, CHECK_POLICY=ON

GO

ALTER LOGIN [RSSO_USER] ENABLE

GO

USE [rsso]

GO

EXEC sp_changedbowner 'RSSO_USER'; 

 

The database, user name and passwords are all changeable, the above are the default out of the box values.

 

2. Open the database.properties file and place the following lines in, change the file to reflect your environment

 

database-type=MsSql

db-url=jdbc:sqlserver://localhost:1433;instanceName=MSSQLSEVER;databaseName=rsso;

db-user-id=RSSO_USER

db-password=RSSO#Admin#

 

3. Save the file.

4. Open a command prompt and "cd" to the directory you saved the files in

5. confirm java is in the path and is version 7 and over "java -version"

6. Run the following command to begin the process of creating the tables  "java -jar rsso-database-all.jar database.properties"

 

If everything is successful you will see messages indicating that the tables have been created (fig5). Check in Microsoft SQL server Studio for the tables (see fig xx)

 

Fig5.

 

If there are any failures, check the information is correct in the "database.properties" file and the connection to the database, If the problem is still not resolvable contact BMC Support for further advice.

 

FOR ORACLE:

 

1. The first thing we need to do is create the RSSO database (RSSO_USER) user in the database. Run the following SQL to create the user.  Change the password to meet your policy (highlighted in red)

 

CREATE USER RSSO_USER IDENTIFIED BY RSSO#Admin#;

ALTER USER "RSSO_USER" QUOTA UNLIMITED ON USERS;

GRANT CONNECT, RESOURCE TO RSSO_USER;

COMMIT;

 

The database, user name and passwords are all changeable, the above are the default out of the box values.

 

2. Open the database.properties file and place the following lines in, change the file to reflect your environment

 

database-type=Oracle

db-url=jdbc:oracle:thin:@localhost:1521:orcl

db-user-id=RSSO_USER

db-password=RSSO#Admin#

 

3. Save the file.

4. Open a command prompt and "cd" to the directory you saved the files in

5. confirm java is in the path and is version 7 and over "java -version"

6. Run the following command to begin the process of creating the tables  "java -jar rsso-database-all.jar database.properties"

 

If everything is successful you will see messages indicating that the tables have been created (fig6). Check in Oracle Developer for the tables (see fig7)

 

Fig6.

 

If there are any failures, check the information is correct in the "database.properties" file and the connection to the database, If the problem is still not resolvable contact BMC Support for further advice.

 

After the user and tables have been created, the install of RSSO can continue by using the "Use Existing User" option on the installer.

 

Fig7 Shows the creation of the tables for MSSQL & Oracle (version 9.1 SP4 RSSO)

Share:|

There maybe some instances where you need to point RSSO enables applications to a new or test RSSO server. These applications include Remedy AR server/Midtier, TrueSight, BMC Atrium Orchestrater and BMC Discovery (ADDM)

 

When would I need to do this?

There maybe some instances where you need to point an already integrated application to a new RSSO server,  some of these reasons can include

  • Decommissioning of an old environment where an RSSO server is installed
  • Troubleshooting purposes where in one environment Authentication is not working as expected and you want to spin up a new RSSO server to see if the same problem exists
  • Upgrading the RSSO webserver (tomcat) you have tested and all is working as expected and you want to point the agents to this new server
  • Server/Domain name changes, where RSSO was initially installed on a particular FQDN and there is a requirement to change the cookie domain and or server FQDN
  • You need to quickly test new Authentications in RSSO
  • You need to test a new configuration of RSSO without having to reinstall or running the application integrations again and don't want to make any changes to a working RSSO system

 

Applications

RSSO enabled application will have different methods of pointing to a new RSSO server. The goal here is to make this process as efficient as possible with limited downtime for the application itself. Applications that do not make use of the internal RSSO user store, such as Remedy Midtier & MyIT is relatively easy, while other applications such as BOA & Truesight  extra work need to be done since maybe the internal users might not be in RemedySSO so will need to be created (users such as bppmws_internal & service_admin for Truesight)

 

Prerequisites

To carry out any of these procedures you will have had to integrate the agent application with RSSO in the first place with the same version of the new RSSO server. You will need to have installed a new RSSO server that you want to point the applications to. Ensure you are able to ping and telnet to the new RSSO server from the application. Telnet on the http or https port of the new RSSO sever by its fully qualified domain name.

 

ping newrssoserver.domain.com                       i.e ping rssolb.bmc.com

telnet newrssoserver.domain.com <port>          i.e telnet rssolb.bmc.com:8443

 

Example in this Blog

In this blog we are going to point our applications from a single server RSSO system to a load balanced enabled environment

 

From

Single server: https://clm-pun-028217.bmc.com:8443/rsso

 

To

https://rssolb.bmc.com/rsso

 

 

Remedy Midtier & Remedy AR Server

To point AR server and midtier to an new RSSO server is relatively easy. Once the new RSSO server is up and running, there are just two configuration files which needs changing

 

On the AR server <AR_SERVER_INSTALL_PATH\ARSystem\Conf\rsso.cfg

On The Midtier <MIDTIER_INSTALL_PATH\WEB-INF\classes\rsso-agent.properties

 

Both of these files have the has the URLs to the RSSO service URL & the midtier's rsso-agent.properties file also hold the sso external url  (The user facing url) for more information on what these urls are for see RSSOAgent docs page . These urls will need to be changed to point to the new RSSO server.

 

AR rsso.cfg file: Its recommended you back up this file before making any changes to it.

Edit  the rsso.cfg file in a text editor. If you are intending to make quick changes from the new server back to the old one then just comment out the SSO-SERVICE-URL parameter

red lines denote the previous setting & green the new entry

----------

# RSSO internal url - HTTP url to RSSO. Use HTTP instead of HTTPS protocol to avoid problems with handshake.

#SSO-SERVICE-URL: https://clm-pun-028217.bmc.com:8443/rsso

SSO-SERVICE-URL: https:/rssolb.bmc.com:8443/rsso

# uncomment the line below if you find the issue that RSSO authenticated users have no groups because of a bug in some old AR versions (e.g. AR 8.0/8.1)

# AR-USER-GROUPS-FIX: true

----------

After making the changes. Restart the AR server service

 

Midtier rsso-agent.properties file: Its recommended you back up this file before making any changes to it.

Edit the rsso-agent.properties file in a text editor If you are intending to make quick changes from the new server back to the old one then just comment out the sso-service-url parameter & sso-external-url (the whole file will not be listed here only where the changes needs to be made)

 

----------

.

.

.

# If this property set to true the application context name will not be excluded for checking excluded url pattern

#context-included=false

# RSSO webapp external url for redirection

# To support multiple RSSO webapps, set the value to a comma separated string: each represents a 'domain to server url' mapping, with the format of <domain>:<url>, e.g. domain1:https://server1:8443/rsso,domain2:https://server2:8443/rsso

#sso-external-url=https://clm-pun-028217.bmc.com:8443/rsso

sso-external-url=https://rssolb.bmc.com:8443/rsso

# RSSO webapp internal url for service call. Use HTTP instead of HTTPS protocol to avoid problems with handshake.

# To support multiple RSSO webapps, set the value to a comma separated string, each represents a 'domain to server url' mapping, with the format of <domain>:<url>, e.g. domain1:http://server1:8080/rsso,domain2:http://server2:8080/rsso

#sso-service-url=https://clm-pun-028217.bmc.com:8443/rsso

sso-service-url=https://rssolb.bmc.com:8443/rsso

 

.

.

.

 

----------

If you have different internal "sso-service-url" & external "sso-external-url" make sure they are updated correctly.

Restart the Midtier Tomcat Service

 

To verify this works go to the midtier URL and try to login. Open the RSSO admin console of the new RSSO server and go to the "Sessions" tab, you should see the user listed there.

If you want to back out the changes either replace the changed files above with a back up version or comment out the changes and un-comment the original entries, then restart the services.

 

 

BMC TrueSight (TSOM)

To point TSOM to an new RSSO server there are a few steps that we need to go through.

 

  1. Export and import users & groups from the source RSSO server to the new target RSSO server
  2. Import the new RSSO server certificate into the TSOM trust store
  3. Run the tssh command on the TSOM server to point to the new RSSO server

 

Exporting & Importing users & groups

We can export the internal RSSO users from the source RSSO server's database. Export the entries from the "LocalUser" "Role" & "RoleLocalUser" tables on the source RSSO server.

The quickest way to to do is to speak to  the database admins and ask them to export the entries from the two tables from the source RSSO server and import it to the new target RSSO server.  If you have access to the database you can run the following DefaultTSOMUsers&GroupsMSSQL.sql file (attached for MSSQL Server), the .sql file are the default users & Groups

that are initially created with the TSOM installer. LDAP users and groups will not be in the RSSO Database as the user store is external.  Once the users & groups have been imported

login to the RSSO admin console and confirm the Users & Roles are listed in "Local User Management" tab.

 

 

 

Importing the new RSSO Certificate in to TSOM

If both RSSO and TSPS are using SSL (HTTPS) we need to import the new RSSO server certificate into the TSOM truststore. The TSOM default trust store "cacerts" can be found on the TSOM server in "\BMC Software\TrueSightPServer\truesightpserver\modules\jre\lib\security" the password is "changeit"

 

Once you have the RSSO server certificate, you can use something like Keystore Explorer to import the certificate into the trust store or use the java keytool command below from the command line.

 

 

 

If java is not in the system path you will need to add the full path to the keytool command "\Java\jre1.8.0_141\bin\keytool.exe"

 

keytool -importcert -alias <*Give a Friendly Alias Name> -keystore cacerts -storepass changeit -file <path to RSSO server certificate>

 

*Alias name can be any name, but normally its a name that specify either what the certificate is or the server name the certificate comes from

 

i.e.

keytool -importcert -alias rssolb -keystore cacerts -storepass changeit -file rssolb.cer

 

You will be asked "Trust this certificate?" type "Yes" if the import is successful a message "Certificate was added to keystore" will be shown.

 

 

TSSH Command to point to new RSSO Server

The final part to point TSOM to the new RSSO installer is to set the "bmc.sso.servername" property using the tssh command on the TSOM server. Assuming that ports and passwords are the same on the new target RSSO server and the old source RSSO server you will only need to change the "bmc.sso.servername" property.  If properties are different then you will need to them to change them using the tssh command before restarting the TSOM server.

 

Syntax

tssh properties set <Property>  <New value>

 

RSSO  Properties

bmc.sso.servername

bmc.sso.password

bmc.sso.port

bmc.sso.servername

bmc.sso.type

bmc.sso.username

 

Fllow these steps to change the TSOM RSSO properties (in this instance only server name will changed)

  1. Open command line and cd in to "\BMC Software\TrueSightPServer\truesightpserver\bin"
  2. Run the following command "tssh properties set bmc.sso.servername <new server FQDN>" i.e "tssh properties set bmc.sso.servername rssolb.bmc.com"
  3. If there are other properties that need changing you can do so following the "tssh properties set <property.name> <New Value>
  4. Check the changed parameter by running "tssh properties list"
  5. tssh server stop
  6. tssh server start

 

Once the TSOM server has restarted fully. Open a browser and go to the TSOM url, you should then be redirected to the new RSSO server for Authentication. If you have already configured

an authentication in RSSO you should be able to login. You can add the local Authentication to RSSO and login with the default TSOM admin account and password (admin/admin12345), you can then confirm the session in the RSSO admin console "Sessions" tab.

Share:|

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

 

Tools

There are a few free LDAP browser tools available two of the easiest ones to use is LDAP Admin & JXplorer . We'll use these tools to browse and get information from the LDAP server

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)

 

  1. Open LDAPAdmin --->Start-->Connect--->Create New Connection
  2. Give a connection name (any descriptive name)
  3. In the "Host" field enter the name of the LDAP server
  4. 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)
  5. Uncheck the "Anonymous Connection" In the user account section
  6. 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
  7. In the "password field" enter the password for the user
  8. 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
  • Port
  • 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

fig1

 

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

fig2

 

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)

 

fig 3

 

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

 

   Connection Settings

`

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)

  1. Enter the server host name in the "Server Host" field
  2. 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)
  3. Enter the BIND DN user in the "BindDN" field
  4. 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)

 

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:

  1. 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"

  1. 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)

 

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)

 

fig 7

 

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.

 

fig 8

 

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.

 

fig 9

 

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.

 

fig 10

 

 

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

 

Nested Groups

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.113556.1.4.1941:=CN=Harry C. ane,OU=UK,OU=Users,OU=Demo Accounts,DC=SSO,DC=BMC,DC=COM))

 

The "1.2.840.113556.1.4.1941" 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.113556.1.4.1941:=$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.

 

fig 15

 

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.113556.1.4.1941:=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.113556.1.4.1941:=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

 

TuesightUserAccount.log

[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:

  1. 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.
  2. 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.

 

fig 16

 

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

  1. 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
  2. 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

  1. Set the RSSO server to debug mode. RSSO Admin console-->General tab-->Basic "Server Log level" = DEBUG
  2. If possible stop the RSSO service and delete the logs from /tomcat/logs then restart the Tomcat service (smaller logs are easier to read)
  3. Reproduce the issue document the date/time
  4. 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..

Share:|

With the introduction of TrueSight 11.00 released October 2017 comes the integration with Remedy Single Sign-on. Up until now the only SSO integration with TrueSight was with Atrium Single Sign-on.

 

There are many advantages of using Remedy Single Sign-On with TS instead of Atrium Single Sign-On, some of which include

 

  • High Availability & Fail over
  • More authentication mechanisms including Kerberos, Certificate, SAML
  • Smaller footprint on the server side and application side (agent)
  • Authentication chaining mode

 

In this post we'll take a look at installing and configuring the TS Presentation Server and Infra Structure Manager 11.00 with Remedy Single sign-on 9.1.03.01

 

INSTALLERS

 

You can download both TrueSight and RSSO from BMC EPD. The required versions are TrueSight Presentation Server & Infrastructure Manager 11.00 & Remedy Single sign-on 9.1.3.01

There are two different installers for RSSO

  • BMCRemedySSO-9.1.03.001 which is the Stand Alone Install of RSSO (supports Oracle, MSSQL databases)
  • Remedy_Single_Sign-On_for_TrueSight_Version_11.0_Windows Integrated Install (supports only PostgreSQL database)
  • TrueSight_Presentation_Server_11.0.00
  • TrueSight_Infra_Mgmt_11.0_CoreComponents

 

Which RSSO installer should you use?

This questions depends on how you are intending to deploy RSSO. In summary the recommendation would be to use the RSSO standalone install. The standalone installer has much more room to expand as requirements gets larger i.e. More users on the system, other BMC applications like Remedy, ADDM, BAO, DashBoards & Analytics. If there are no plans to deploy other applications with RSSO and the userbase is going to stay consistent, then installing Remedy Single Sign-On for TrueSight Version 11 would be sufficient.

 

Stand Alone install VS Integrated Install

  • Stand Alone install supports Oracle and MSSQL as its database's, while the integrated install only supports Postgres
  • Stand Alone Install easily grows with your requirements (users and applications)
  • Integrated install is a black box install and is generally faster to deploy than the standalone install. The stand Alone install requires tomcat pre-installed & separate database, while the integrated install includes Tomcat, Java & postgres database
  • Integrated installer is only recommended for TrueSight applications
  • Both Stand Alone install and integrated install has fail over capabilities, but Oracle's and MSSQL's fail over and load balancing is considered more advance than postgres

 

 

In the following section we'll look at installing both the Stand Alone RSSO Install and the Integrated RSSO install.

 

STAND ALONE INSTALL

 

Things to know before running the installation. It is recommended to install RSSO on its own server in a production environment. During the install you will be asked for

  • Database server name (IP)
  • Admin user for database either system or sa. This will only be used at install time only since the installer will need to create the RSSO_USER database user and its tables.

        if you do not have access to the admin user account you can pre create the database, see Manually configure database for Remedy SSO , if at all possible its better to let the installer

        create the RSSO_USER database user and the tables

  • Apache Tomcat install location (you will need to have installed & configured Tomcat before running the installation latest stable version of Tomcat 7.x but 8.x and above is recommended) Its advisable to have tomcat using SSL see PPT attached "ConfiguringRSSOforHTTPS.pptx"
  • If you are going to be using a Load Balancer for RSSO confirm the LB url with the LB administrators

 

Stand Alone Install Walk Through (Screen shots where needed)

 

Run the installer from BMCRemedySSO-9.1.03.001

 

1. EULA - Read and click agree

 

2. Location where you want the RSSO server files installed

 

3. Select "Install BMC Remedy Single-Sign-on 9.1.03.001

 

4. Location of Tomcat Webserver (Which should have been installed and configured already)

5. Database connection details

 

6. Database user name. Here you have the option of using an admin account to create the RSSO_USER database user or use Existing user which should have been created and configured in advance see Manually configure database for Remedy SSO . The admin user in this case "sa" will be used to create the RSSO_USER account and tables only used during the install phase. Supply RSSO_USER database user password (note this is the DB user not the admin user used to login to RSSO admin console)

 

 

7. Cookie domain name. This is picked up automatically from the server's FQDN. If this is incorrect check to see if there are multiple NICs on the server and confirm which NIC should really be in use. RSSO is reliant on domain names to function correctly as its used to verify client calls, creating sessions & Tokens (can be changed after installation)

 

 

8. Install summary. Click "Installed" to continue.

 

Where to specify the ports?

The installer uses the ports configured with tomcat. Default ports for TC is 8080 HTTP & 8443 HTTPS

 

Warning and errors during the install. If the installer finishes with warning this is generally OK (the warning is likely to be tomcat taking a little while longer to start up)

If you get any errors with this installs and it fails, open a support case with BMC support (Atrium CMDB team) attach the install logs which can be found in the %temp% (windows) or /tmp (linux)

 

 

Integrated RSSO Install Walk Through (Screen shots where needed)

 

Run the installer from Remedy_Single_Sign-On_for_TrueSight_Version_11.0

 

1. EULA - Read and click agree

 

2.  Location where you want the RSSO server files installed

3. Database information, will install PostgresSQL locally or you have the option to connect to an external Postgres database

4. Enter the Postgres database details. Passwords for the postgres admin User and rsso_user database user

5. Enter HTTPS & HTTP ports for the tomcat webserver if selecting another port run "netstat -an" to ensure the port is not in use. Default HTTP 88, Default HTTPS 448

 

 

6. Cookie domain name. This is picked up automatically from the server's FQDN. If this is incorrect check to see if there are multiple NICs on the server and confirm which NIC should really be in use. RSSO is reliant on domain names to function correctly as its used to verify client calls, creating sessions & Tokens (can be changed after installation)

 

 

7. Install summary. Click "Installed" to continue.

 

Warning and errors during the install. If the installer finishes with warning this is generally OK (the warning is likely to be tomcat taking a little while longer to start up)

If you get any errors with this installs and it fails, open a support case with BMC support (Truesight team) attach the install logs which can be found in the %temp% (windows) or /tmp (linux)

 

 

Verifying RSSO Server Installation

 

Once the install is done run through the following process to verify the installation

 

Windows OS: For the stand alone install check  the tomcat server is running. For the integrated install check the following service is configured and running "BMC Remedy Single Sign-On Server"

 

Linux OS: Check the tomcat process is running with "ps -ef | grep tomcat"

 

Login to the RSSO web admin console https://rssoserver.fqdn.com/rsso/admin/# The default user name and password is

User: Admin

Password: RSSO#Admin#

you can change the default password in the RSSOAdmin console. Check to see if the TrueSight default users and group have been created in RSSO Admin console "Local User Management" tab

 

 

Installing TrueSight 11.00 walkthrough (sso related screen shots shown only)

 

The first Truesight component that needs to be installed is the Presentation Server (TSOM). Things to know before running the installation.

  • RSSO server Fully Qualified domain name
  • RSSO Tomcat port HTTP or HTTPS
  • If RSSO Tomcar is running HTTPS copy the Tomcat Server certificate to the machine where TSOM will be installed (during the install you will import this if RSSO server is a standalone install)

 

If RSSO was installed with the RSSO integrated installer you don't necessarily need to import the server certificate during the installation, you can do this after the install (see "importing RSSO server certificates after install" section below)

 

Presentation Server install (TSOM)

 

Run the installer TrueSight_Presentation_Server_11.0.00

 

1. EULA - Read and click agree

 

2. Ensure the FQDN of the server name is filled out (not short name) RSSO is reliant on domain names to function correctly as its used to verify client calls, creating sessions & Tokens

 

3.   Enter the FQDN of the RSSO server & port TC is running on. HTTPS is recommended (see PPT attached "ConfiguringRSSOforHTTPS.pptx")

      Enter the RSSO admin user password default is RSSO#Admin#. You will be asked if you want to import the RSSO SSL Certificate if you have the RSSO server certificate click "yes"

      and browse to it, its recommended to do the import here so you won't have to manually do it later. If you are running RSSO with the Integrated install and have not signed the RSSO

      server SSL certificate you can choose no, since the default server certificate is installed with TSOM. You can install the RSSO server certificate after the install manually (see          "importing certificates after install" section below)

 

4. Review installation summary and install

 

 

Importing RSSO server certificates after install

If the RSSO server certificate was not imported during the install, it must manually be done after the install. The following steps goes through this process by using the keytool utility

to import the RSSO Server certificate into the TSOM truststore

 

Set the following environment variables

 

#Microsoft Windows

set PATH=<Presentation Server Installation Directory>\truesightpserver\modules\jre\bin;%PATH%

#Unix

export PATH=<Presentation Server Installation Directory>/truesightpserver/modules/jre/bin:$PATH

 

1. Obtain the RSSO Server certificate and place it in \truesightpserver\modules\jre\lib\security directory

2. backup the TSOM trustore file \truesightpserver\modules\jre\lib\security\cacerts

3. Open a command prompt and cd to the \truesightpserver\modules\jre\lib\security directory

4. run the following keytool command

     keytool -import -alias remedysso -file rssoservercert.cer -keystore cacerts -storepass changeit

a message saying "Trust this certificate? [no]: " will appear type "Yes"

When the certificate has been imported successfully, a message saying "Certificate was added to keystore" will be displayed

5. To confirm the certifiate was imported correctly run the following keytool command

  keytool -list -keystore cacerts -storetype JKS -storepass changeit -alias remedysso

the result of the keytool list command should be similar to

 

#

6. Restart the TSOM service

 

 

Infrastructure Manager Server install (TSIM)

 

Run the installer TrueSight_Infra_Mgmt_11.0_CoreComponents

 

The infrastructure manager installer will not ask information about RSSO, this information is stored on the TSOM server where TSIM will be registered as a component. There is a section in the TSIM install where the installer asks to "Confirm your localhost Fully Qualified Domain Name (FQDN) ensure the FQDN is used and not the short DNS name

 

 

Logging into TSOM

 

1. Open a browser and enter the URL for TSOM

2. The browser will redirect you to RSSO with a final url of something like

     https://RSSOSERVER.bmc.com:448/rsso/start?goto=https%3A%2F%2TSOMSERVER.bmc.com%3A444%2F&tenant=*@*  this is expected and working as designed

3. login with the default TS user admin account default is

     User: admin

    Password: admin12345

4. Once logged in successfully you will see the TSOM default page

5. Open the RSSO admin console in a new tab and login with the RSSO Admin user default is

     User: Admin

     Password: RSSO#Admin#

6 On the RSSO admin console got to the session tab you should see the admin user listed in the sessions list

Logging into TSIM

 

You won't be able to login to TSIM until you have registered the TSIM server as a component in TSOM

 

1. Open a browser and enter the URL for TSIM

2. You will be asked to enter your application domain with out of the box configuration use " * " (you will configure this to your domain name at a later stage)

3. The browser will redirect you to RSSO with a final url of something like

     https://RSSOSERVER.bmc.com:448/rsso/start?goto=https%3A%2F%2TSIMSERVER.bmc.com%3A444%2F&tenant=*@*  this is expected and working as designed

4. login with the default TS user admin account default is

     User: admin

     Password: admin12345

If you have installed RSSO integrated install you will now be able to login to TSIM .

5. Once logged in successfully you will see the TSIM default page

6 On the RSSO admin console go to the session tab, you should see the admin user listed in the sessions list

 

If you have installed RSSO as a stand alone server and try to login to TSIM you will see the following error when you try to login

This is because the TSOM server certificate is not in the TSIM keystore. To resolve this you will need to import the TSOM certificate in to the TSIM keystore.

 

Before doing the import  add  jre/bin to the PATH environment variable

 

#Microsoft Windows

set PATH=<Infrastructure Management Server Installation Directory>\pw\jre\bin;%PATH%

#Unix

export PATH=<Infrastructure Management Server Installation Directory>/pw/jre/bin:$PATH

 

Importing TSOM Certificate into TSIM Keystore

 

The following procedure uses the java keytool utility to import the TSOM server certificate into the TSIM keystore.

 

Obtain the TSOM server certificate and place it on the TSIM server in \BMC Software\TrueSight\pw\pronto\conf directory

 

1. Backup the pnserver.ks file from \BMC Software\TrueSight\pw\pronto\conf directory

2. open a command prompt and go to the \BMC Software\TrueSight\pw\pronto\conf directory directory

3. Run the following command to see what certificates is in the pnserver.ks keystore  

keytool -list -keystore pnserver-update.ks -storetype JKS -storepass get2net This will list certificates in the keystore

If the keytool list command output returns an entry similar to

 

truesightserver, Oct 12, 2017, trustedCertEntry,

Certificate fingerprint (SHA1): 63:DC:89:F1:87:C1:87:2F:F8:85:6B:7E:B4:F6:1F:76:

30:1D:D3:5E

 

This means the truesightserver certificate from TSOM is already in the keystore. Out of the box with TSOM 11.00 the certificate is not there. If the certificate is there then there is no need to import it again, unless you are getting the  "Initialization of connection is in progress, or the connectivity was lost between the Infrastructure Management Server and the Presentation Server" error when login in to TSIM, so you will need to delete the certificate by running the following keytool command

keytool.exe -delete -alias truesightserver -keystore pnserver-update.ks -storepass get2net

 

4. Run the following keystore command to import the TSOM certificate into the TSIM keystore

 

keytool -importcert -trustcacerts -alias truesightserver -keystore pnserver.ks -file <TSOM certificate> -storetype JKS -storepass get2net

i.e

keytool -importcert -trustcacerts -alias truesightserver -keystore pnserver.ks -file presentationserver.cer -storetype JKS -storepass get2net

 

A message of  "Trust this certificate? [no]:" will appear, type "yes"

 

If the certificate was imported successfully you will get a "Certificate was added to keystore" message

 

5. If you have the CAroot certificate and or intermediate certificates they can be imported into the keystore also by running the keytool import command

keytool -importcert -trustcacerts -alias truesightserver -keystore pnserver.ks -file <CA/Intermid certificate> -storetype JKS -storepass get2net

 

6. Restart the TSIM service.

 

7. The browser will redirect you to RSSO with a final url of something like

     https://RSSOSERVER.bmc.com:448/rsso/start?goto=https%3A%2F%2TSIMSERVER.bmc.com%3A444%2F&tenant=*@*  this is expected and working as designed

8. login with the default TS user admin account default is

     User: admin

     Password: admin12345

9. Once logged in successfully you will see the TSIM default page