White Paper

July 2006

Integrating BMC® Remedy®

Action Request System®
with Single Sign-On (SSO)
Authentication Systems and
Other Client-Side Login
Intercept Technologies
Copyright 1991–2006 BMC Software, Inc. All rights reserved.

BMC, the BMC logo, all other BMC product or service names, BMC Software, the BMC Software logos, and
all other BMC Software product or service names, are registered trademarks or trademarks of BMC
Software, Inc. All other trademarks belong to their respective companies.

BMC Software, Inc., considers information included in this documentation to be proprietary and
confidential. Your use of this information is subject to the terms and conditions of the applicable end user
license agreement or nondisclosure agreement for the product and the proprietary and restricted rights
notices included in this documentation.

For license information about the OpenSource files used in the licensed program, please read
OpenSourceLicenses.pdf. This file is in the \Doc folder of the distribution CD-ROM and in the
documentation download portion of the product download page.

Restricted Rights Legend

U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE
COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the
U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS
252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is
BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.

Contacting Us
If you need technical support for this product, contact Customer Support by email at
support@remedy.com. If you have comments or suggestions about this documentation, contact
Information Development by email at doc_feedback@bmc.com.

This edition applies to version 7.0 of the licensed program.

BMC Software, Inc.

www.bmc.com
White Paper

Integrating AR System with single sign-

on (SSO) authentication systems
This white paper discusses integrating BMC Remedy Action Request System
(AR System) with single sign-on (SSO) authentication system. The paper
includes the following topics:
„ Introduction (page 4)
„ Overall philosophy and architecture (page 5)
„ Web client (6.3 and later) (page 6)
„ Windows client (7.0 and later) (page 10)
„ Custom API program (page 14)
„ Server—AREA (6.0 and later) (page 14)
„ Server configuration (various releases for different options) (page 16)
„ Code samples (page 19)

Integrating AR System with single sign-on (SSO) authentication systems W 3

White Paper

Introduction
Many forces in the marketplace today are leading companies to rethink how
they control access to applications within their environment. The traditional
prompt for user name and password is not meeting the needs of these
customers.
One key example is the mixed application environment. When users are
accessing a series of related applications, how do they move from application
to application without having to re-enter their user information for each
application? How can they seamlessly flow between applications in a secure
and safe way? Single sign-on technologies allow for this type of interaction.
Another example is improved security. Some customers are looking at a
more secure method for connecting. This might be using the secure card
technology or a biometric validation methodology. The goal is to require
additional data that is more personal and more difficult to duplicate. In these
cases and others, the key is to change the way that applications gather
credentials but to still allow access to the system with the same capabilities
and security as if the application had been started in the traditional way.
The focus of this white paper is to discuss the mechanisms within the BMC®
Remedy® Action Request System® (AR System) environment for addressing
these types of requirements. The discussion starts with an overview of the
approach and philosophy of how to solve the problem. It continues with
details of the work required in clients to implement this capability and the
work required on the server to complete the implementation and ensure
security within the environment.
Everything discussed in this paper is available with AR System 7.0. The
concepts apply to 7.0 and later releases of the system. Details of parameters
and calls might change slightly between releases, so verify the interfaces with
the version of the system you are using. Some portions of this
implementation are available in earlier versions of the system (for example,
Web client and AR System server plug-in support is available in 6.3), but for
full support for all aspects, you must be using version 7.0.

4 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

Overall philosophy and architecture

There are many technologies, and there are many implementations of those
technologies. Trying to build into the system-specific support for a subset of
the solutions that are available would limit the system to only those
environments. Accordingly, the approach taken with the implementation
involves adding the necessary hooks to the environment to allow you to plug
in the logic that integrates with the solution and technology that your
environment needs.
The solution is straightforward, but it involves some coding or the use of
modules that others have coded:
1 On the client, intercept the login step of the client and gather user credentials
from the technology you are integrating with. A user name must be obtained,
and other information is usually obtained to verify the user. For more
information, see:
„ “Web client (6.3 and later)” on page 6
„ “Windows client (7.0 and later)” on page 10
„ “Custom API program” on page 14
2 On the server, given the set of credentials and using the technology you are
integrating with, validate that the user is a valid user. (This is a critical step in
the process.) For more information, see “Server—AREA (6.0 and later)” on
page 14.
3 Configure the server options so that the server will pass the credentials to
your authentication check and allow the code to perform the authentication.
For more information, see “Server configuration (various releases for
different options)” on page 16.
You might be using several authentication methodologies at the same time.
You can use an SSO environment within the office but have users enter their
user name and password if they are working from home. This strategy allows
you to mix multiple methods and let the authentication automatically
validate against each of them.
This approach allows you to integrate with any technology or environment
for authentication. It completes the journey begun with the introduction of
the AREA feature of the AR System server for external authentication in
version 6.0. You can now link to technologies on the client to provide a
complete, end-to-end implementation of using an external environment or
technology for authentication within the system.

Overall philosophy and architecture W 5

White Paper

The following sections discuss what is needed within each piece of the
product.

Web client (6.3 and later)

From the Web client, a hook is in place to allow you to specify alternate logic
for gathering login data that will be called instead of the login page at startup.
This logic can do whatever work you want—interact with other systems,
open windows, perform calculations, and so on.
This logic is needed to return the login information that would have come
from the login page. If the alternate method is not present or if there is a
problem getting the information, see the discussion of the fallback
mechanisms later in this section.
When the login page is launched, the client will call the registered
authentication logic and look for the getAuthenticatedCredentials
method.

Important: The alternate logic must be registered with the system and the
appropriate Java file in place, or it will not be found. See the following
section for details about how to register the alternate authenticator.

Authenticator
The plug-in to the mid tier consists of three routines: init, destroy, and
getAuthenticatedCredentials. You must implement these routines in Java
and then register them for your code to be called. Remember to copy the Java
file to the appropriate location according to your definition so that it can be
found.

6 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

The authenticator com.remedy.arsys.session.Authenticator interface is

given by:
public interface Authenticator {
public void init(Map config)
public void destroy()
public UserCredentials getAuthenticatedCredentials
(HttpServletRequest request,
HttpServletResponse response)
throws IOException;
}

where UserCredentials is a data-object class with the following constructor:

public UserCredentials(String user, String password, String
authenticationStr)

The getAuthenticatedCredentials() method throws IOException to

simplify the support of the methods of the HttpServetRequest and
HttpServletResponse classes.

In the default configuration of the mid tier, an instance of the

com.remedy.arsys.session.DefaultAuthenticator class will perform the
login and authentication.

init()
The authenticator should use the init() routine to perform initializations.
The routine is called one time at startup of the mid tier.
After the mid tier instantiates an instance of the authenticator by using
reflection, it builds an object of type java.util.Properties using the
properties specified in the file that the
arsystem.authenticator.config.file entry indicates in the
config.properties file. This file is a map of the name-value order pairs. For
example:
arsystem.authenticator.config.file=myauthenticator.properties

In a normal deployment, the myauthenticator.properties property file,

(used in the example) must be in the same directory as the
config.properties file (for example, in WEB-INF/classes). If no entry for
the authenticator init file exists in the config.properties file or if the mid
tier cannot locate or open the file referenced in the
arsystem.authenticator.config.file entry, the mid tier creates an empty
properties object. This object is then passed into the init() method.

Web client (6.3 and later) W 7

White Paper

If any of the parameters that can be externalized are needed during the
authenticator initialization process, they should be placed in a separate file.
The file name must be registered in the config.properties file under the
arsystem.authenticator.config.file entry.

destroy()
When the mid tier is being unloaded from the application server, it calls the
destroy() method of the authenticator. Any cleanup of resource usage
should be done here.

getAuthenticatedCredentials()
The getAuthenticatedCredentials() method is the main method of the
plug-in. This method is called for each user who connects to the system.
The implementation of this method is divided into two cases (depending on
the SSO environment configuration):
„ When the mid tier is deployed behind a proxy—The mid tier is deployed
in an SSO environment where each request that reaches the mid tier is
guaranteed to have been authenticated. The
getAuthenticatedCredentials() method is called only when the mid tier
must retrieve the user credentials to establish a session for the user. Here,
the method must return the UserCredentials object. The object’s value is
used to establish a session for the user, and then it is wrapped and passed,
as is, to the AR System server when the mid tier constructs a request on
behalf of the user.
If the returned UserCredentials object is in an invalid format (for
example, missing the user name), the mid tier will default to the
DefaultAuthenticator, the normal login mechanism of the mid tier.

In summary, if the mid tier is deployed behind a proxy, guaranteeing that

any request reaching the mid tier has been authenticated, then the
getAuthenticatedCredentials() method will extract the user credentials
that are specific to the protocol of the SSO environment from the request,
construct a UserCredentials object, and return that object as the return
value.

8 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

„ When the mid tier is not deployed behind a proxy—The mid tier is
deployed so that it must route unauthenticated requests to a configured
SSO service. It has the additional responsibility of routing the pre-session
establishment requests to the SSO service. This is achieved by
synchronizing the mid tier with the configured authenticator.
The mid tier will invoke the getAuthenticatedCredentials() method
only when it needs to establish a session for the user.
In the context of pre-session establishment, when the user request arrives,
the mid tier calls the getAuthenticatedCredentials() method, passing
both the HttpServletRequest and HttpServletResponse objects.
At this point, the authenticator examines the HttpServletRequest object
to see whether the SSO token is embedded inside the
HttpServletRequest. (The embedding protocol is specific to the SSO
environment.)
If the token is embedded, the method extracts the information, constructs
a UserCredentials object, and returns this object as the return value.
If the token is not embedded, the method embeds the routing information
to the SSO service in the HttpServletResponse object and returns null.
When the mid tier receives null, it routes the HttpServletResponse object
to the Servlet container so that the user request is redirected to the SSO
service.
After the SSO service has authenticated the user, it embeds the SSO token in
the HttpServletRequest object, reconstructs the original request, and routes
it back to the mid tier. At this point, the behavior is the same as described in
the first case.

Registration of the authenticator

You must register the alternate authenticator, or the system will not know
about it.
When the mid tier is initialized, it uses reflection to instantiate an instance of
the authenticator. The fully qualified name of the class implementing the
alternate interface must be specified in the config.properties file under the
arsystem.authenticator entry. (In a default deployment, the
config.properties file is found in the WEB_INF/classes directory.)

Web client (6.3 and later) W 9

White Paper

The following example defines DefaultAuthenticator as the authenticator

to be used:
arsystem.authenticator=com.remedy.arsys.session.DefaultAuthenticat
or

This is the default authenticator that displays the login screen. It will be used
if you do not have an alternate authenticator defined.
Only one registration is permitted for the instantiation of the mid tier, so
only a single alternate authenticator mechanism is allowed for an instance of
the mid tier.

Fallbacks and the default login page

If a problem occurs during login, the system will fall back to the standard
login page and allow the user to continue logging in to the system through
that approach.
If any of the following conditions occur, the default login page will be
displayed:
„ The plug-in implementation is not found or cannot be run.
„ A call returns incomplete or inconsistent data (for example, a blank user
name).
„ The login using credentials from the plug-in returns an error indicating
login failure.
In each of these cases, the Web client will display the standard login page and
allow the user to attempt connection using the standard user name,
password, authentication string login. Specifically, the
DefaultAuthenticator method will be called.

Windows client (7.0 and later)

Note: This discussion applies to BMC Remedy User and BMC Remedy Alert.
BMC Remedy Administrator always requires a login and will not support
an “auto-login” mode because the tool allows changing of the definitions
of the system. The login to that tool acts as a verification of the identity of
the user.

10 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

BMC Remedy User and BMC Remedy Alert include a hook that allows you
to specify a DLL that will be called instead of the login page at startup. This
DLL can do whatever work you want—interact with other systems, open
windows, perform calculations, and so on.
This DLL returns the user’s login information, which would have come from
the login page. If the DLL is not present or if there is a problem getting the
information, see “Fallbacks and the default login page” on page 10.
At startup, the login page is launched (unless the user preference has been set
to remember login information). Whenever the login page is launched at
startup, BMC Remedy User and BMC Remedy Alert will look for the
ARSSOInfo.dll DLL with two methods exposed: ARGetSSOLoginCredentials
and ARGetSSOServerInformation. (The second method is optional).

Important: The ARSSOInfo.dll DLL must be placed in the same directories

from which BMC Remedy User and BMC Remedy Alert are launched;
otherwise, the DLL will not be found.

ARGetSSOLoginCredentials
The following method provides credentials for the user.
void ARGetSSOLoginCrendentials(
ARSSOUserCredentialsStruct *pUserCredentialStruct)

The method should load data into the structure for return to the AR System.
This call must be implemented in the DLL.
The goal of this method is to return a user name and additional information
such as a password or a key for the user. This password or key should be
dynamic and tied into the authentication method you will use on the server
to validate this user.

Note: BMC Remedy User allocates all memory for the structure. The fields
are initialized before the method is called. The DLL is responsible for
updating the appropriate fields in the structure. The DLL must not
allocate memory for this structure (but it can allocate and free any
temporary storage it might need for processing), and the DLL must not
write data outside the length limits of the fields.

Windows client (7.0 and later) W 11

White Paper

Following is an example:
struct ARSSOUserCredentialsStruct
{
char* m_szARUserName;
char* m_szARPassword;
char* m_szARAuthenticationString;
BOOL m_bARUsingPreferenceServer;
int m_nARNumberOfServers;
};

„ m_szARUserName—The login name of the user. The maximum length is

254 bytes. The string must be null terminated. A value must be specified
for this field. There is no default value.
„ m_szARPassword—The password for the user. The maximum length is 30
bytes. The string must be null terminated. The default is an empty string.
„ m_szARAuthenticationString—The authentication string for the user.
The maximum length is 2000 bytes (254 bytes for versions of 7.0 before
patch 2 of BMC Remedy User because an incorrect length was used
initially). The string must be null terminated. The default is an empty
string.
„ m_bARUsingPreferenceServer—A flag indicating whether the login will
be using a preference server. If set to TRUE, a preference server is expected
and the m_nARNumberOfServers field must have a value of 1 or greater. If
set to FALSE, there is no preference server. The default is FALSE.
„ m_nARNumberOfServers—The number of servers that will be specified by
the plug-in for this user. If this parameter is set to 0, no additional servers
are expected. If set to a number greater than 0, the
ARGetSSOServerInformation method will be called to get the list of
servers. If the m_bARUsingPrefereceServer flag is set to TRUE, the value of
this parameter must be at least 1 to accommodate the preference server.
The default is 0.

ARGetSSOServerInformation (optional)
The following method is optional:
void ARGetSSOServerInformation(
ARSSOServerInformation *pServerInfo)

12 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

If the user wants to provide only login credentials and does not want to
provide server list information, this method is not needed. If the method is
not present, the system will use the default mechanism of looking at the local
configuration file to determine which servers to connect to. If the server
count field from the ARGetSSOLoginCredentials specifies a count of the
number of servers of greater than 0, this method is required.
Treat the parameter as an array of items with each item having the structure
described. The size of the array is determined by the server count returned in
the ARGetSSOLoginCredentials method. The server identified in the first
element of the list is treated as the preference server if the login credentials
have indicated a preference server is being used.

Note: BMC Remedy User allocates all memory for the structure. The fields
are initialized before the method is called. The DLL is responsible for
updating the appropriate fields in the structure. The DLL must not
allocate memory for this structure (but it can allocate and free any
temporary storage it might need for processing), and the DLL must not
write data outside the length limits of the fields.

Following is an example:
struct ARSSOServerInformation
{
char* m_szARServerName;
int m_nARTCPNum;
int m_nARRPCNum;
};

„ m_szARServerName—The name of an AR System server to access. The

maximum length is 254 bytes. The string must be null terminated. A
value must be specified for this field. There is no default value.
„ m_nARTCPNum—The TCP socket to which you will connect on this server.
Setting the value to 0 indicates that there is no predefined TCP socket to
connect to (or you will look it up using portmapper). The default value is
0.

„ m_nARRPCNum—The RPC socket to which you will connect on the

AR System server. Setting the value to 0 indicates you are not locking to a
specific RPC socket and will let the system determine which socket to
route to. The default value is 0.

Windows client (7.0 and later) W 13

White Paper

Fallbacks and the default login page

If there is a problem during login, the system will fall back to the standard
login page and allow the user to continue logging into the system through
that approach.
If any of the following conditions occur, the default login page will be
displayed:
„ The plug-in DLL cannot be found or cannot be loaded. (The DLL is
expected to be in the directory from which BMC Remedy User or BMC
Remedy Alert is launched.)
„ An expected method is not exposed from this DLL.
„ A method returns incomplete or inconsistent data (for example, a blank
user name).
„ The login using credentials from the plug-in returns an error indicating
login failure.
„ The user selects the Login option from the Tools menu.
In each of these cases, BMC Remedy User or BMC Remedy Alert will display
the standard login page and allow the user to attempt connection using the
standard user name/password/authentication string login.

Custom API program

The Windows and Web clients that AR System supplies are two possible
clients to the AR System environment. Many other clients can access the
system through the API.
For those clients, we cannot detail the specifics of how they would work
within this environment, but the principle is the same. There must be some
way for the client to obtain login information. This can be hard coded, it can
prompt the user, or it can use an interface to interact with an SSO or alternate
login technology to obtain the user name, password, authentication
information just like the plug-ins for the Windows and Web environment
described in this document.
The client program can determine how it obtains the login information, but
the program must obtain it in a format that the validation logic expects on
the server.

14 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

Other clients of the AR System server must be investigated to determine if

you can integrate with the same alternate login techniques of the clients
provided with the system.

Server—AREA (6.0 and later)

Regardless of anything else you do or do not implement in this overall
process, you must implement the server AREA plug-in to validate the user.
All security enforcement and user validation is performed on the server
within the AR System environment. No authentication is performed on the
client to avoid situations where a client could validate and allow a user when
the client has done no checking and is trying to break security. By always
validating the user on the server, the client cannot spoof or work around the
security of the system to gain access for which it is not permitted.
The server will receive a triplet of information, which you can use to
authenticate the user:
„ User name—Required. The name of the user that the AR System will use.
„ Password—Optional. The password that is used to validate the user.
„ Authentication string—Optional. Key data that is used to validate the
user.
The authentication could use the AR System User form if the user credentials
you have gathered are represented there. It could use a packaged plug-in like
the LDAP AREA plug-in. Or, it could use a custom AREA plug-in with the
authentication logic built in. In any case, the server must authenticate the
user using one of these techniques.
For a full discussion of the AREA API and how to write an AREA plug-in, see
the BMC Remedy Action Request System 7.0 Integrating with Plug-ins and
Third Party Products guide. For information about the C API, see the BMC
Remedy Action Request System 7.0 C API Reference guide.

Note: If the mechanism you are using does not allow you to get the real user
name for the AR System but is an identifier for the name, you can look at
the user name alias functionality of the AR System. This functionality
enables you to have one name as the name used for login and a different
name being the user that is visible in the system. For more information,
see the BMC Remedy Action Request System 7.0 Configuring guide.

Server—AREA (6.0 and later) W 15

White Paper

A key characteristic of AREA is that the plug-in is used for authentication,

but it can also optionally supply authorization information. A plug-in can
return information like the user's email address, a group list, and a license
type (although it cannot return a Fixed license). If the plug-in does not
supply this information, it can be obtained from the user record within the
AR System. If the authorization information is in neither place, the email
address is the login name, the user is in no groups, and the user is defined to
have a read license. This is also further documented in the discussion of the
AREA environment in the BMC Remedy Action Request System 7.0
Integrating with Plug-ins and Third Party Products guide.

Server configuration (various releases for different

options)
Several server configuration settings affect the operation of the system in
relationship to the AREA plug-ins. Some are related only to the AR System
server while others are associated with how AR System interacts with the
AREA environment.
Each of the server options that are related to authentication is listed here
along with a discussion of the option and how it interacts with SSO/login
intercept authentication. The options can be used in any combination of
other options.
All options are documented in BMC Remedy Action Request System 7.0
Configuring guide.

Cross-reference blank passwords (6.0 and later)

The option to cross-reference blank passwords specifies that if a user is
defined within AR System and has no password, the system should look to an
external mechanism to validate the password. This could be the default OS
environment password (for the user with a matching name), or it could be
an AREA plug-in.
This option is independent of the option described in the next section, where
AR System authentication can be included within the validation chain. The
cross-reference option is related only to users defined within the AR System
User form who have no password. It does not accept a user with no password,
but checks the user’s password against an AREA plug-in (if present) or the
OS (if no AREA plug-in is present).

16 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

This option should be used when you want to define characteristics of the
user (such as email address, licensing, group information) in AR System but
have authentication occur outside. So, you can have authorization within the
AR System User form but authentication outside.

Authenticate unregistered users (6.0 and later)

The option to authenticate unregistered users is also known as the Allow
Guest Users option.
This option can be set to allow a user to be permitted read access on the
system if the user is not known to the system or an AREA plug-in (if one is
present). Any user known to the system must properly authenticate. So, any
registered user must have the correct password information supplied to allow
access. But, an unregistered user can be set to have access or not by this
option. If an unregistered user is granted access, they are a member of no
permission groups and are granted a read or restricted read license
(depending on a configuration setting).
This option should be set to permit unregistered users (allow guest users)
when you want to allow unknown users into the system for controlled read
access (within Public permissions) instead of having to formally register each
user in advance. It should be set to require authentication of unregistered
users (disallow guest users) if you want to require that every login be
authenticated within the AR System, the OS, or an AREA plug-in.

Authentication chaining (6.3 and later)

The authentication chaining option allows you to specify that you are using
multiple authentication methods to authenticate the user:
„ Using AR System authentication and an AREA plug-in
„ Using multiple AREA plug-ins
„ Using AR System and multiple AREA plug-ins
This would allow a user to use different mechanisms under different
conditions to connect to the system. For example, from an internal
environment, the user can use authentication through an SSO mechanism
where a user name and password is used, and the user must log in when
coming from outside the environment.

Server configuration (various releases for different options) W 17

White Paper

The Authentication-Chaining-Mode setting in the ar.cfg (ar.conf) file

allows you to configure the behavior of the system. The values supported are
defined in the following table.

Behavior Setting
Use the default behavior as in pre-6.3 release (that is, 0
authenticate either with AR System or with AREA depending
on the settings of other configuration options).
Use AR System internal authentication first, then use external 1
authentication via the AREA plug-in.
Use external authentication via the AREA plug-in first, then 2
use AR System internal authentication.

Separate from this setting is the idea of having multiple AREA plug-ins to
authenticate against many different external sources. In all cases of the
chaining in the table, authentication via the AREA plug-in includes
situations with one plug-in and those having multiple plug-ins.
For those situations having multiple AREA plug-ins, the system can be set up
to use the AREA plug-in hub. The AREA plug-in hub provides a sequential
chaining of multiple AREA plug-ins. From the AR System perspective, there
is one AREA plug-in—the AREA hub. That hub then traverses the various
plug-ins registered with it until it gets a successful authentication or runs out
of plug-ins to try.
The use and configuration of the AREA plug-in hub is documented in the
BMC Remedy Action Request System 7.0 Integrating with Plug-ins and Third
Party Products guide.

Maximum number of bad password attempts before invalidating

the account (7.0 and later)
The option that sets a maximum number of bad password attempts is related
to authentication within the AR System server environment only. Any rules
or checking for bad password attempts through other environments are
enforced strictly through that environment.

18 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

Any AREA plug-in that interacts with an external environment will count
any failed validation against that environment as a bad authentication
attempt. This is even though there might be a successful validation against
another plug-in in the chain. The net effect can be a problem. If logins are
allowed using numerous mechanisms, you should attempt the most
common or the ones with no lockout early in the list so you do not lock out
an account through checks against one environment when the user is logging
in using a different environment.
The AR System option to limit the number of bad password attempts has a
bad attempt recorded only if the login fails all of the tests. This means that
when you want to include AR System authentication in the authentication
chain, configure the chaining to try the AR System authentication first. This
is because a failure there will not count against you if some other
authentication works, and, if AR System authentication succeeds, you
prevent the bad attempts against other authentication mechanisms.

Code samples
You can use the following sample code to help you create AREA plug-ins for
Windows or the Web.

Windows (.cpp file) sample

#include <string.h>

struct ARSSOServerInformation
{
char * m_szARServerName;
int m_nARTCPNum;
int m_nARRPCNum;
};

struct ARSSOUserCredentialsStruct
{
char* m_szARUserName;
char* m_szARPassword;
char* m_szARAuthenticationString;
bool m_bARUsingPreferenceServer;
int m_nARNumberOfServers;
};

extern "C"

{
__declspec(dllexport) void ARGetSSOLoginCrendentials(ARSSOUserCredentialsStruct
*pUserCredentialStruct)

// The required memory for struct ARSSOUserCredentialsStruct is allocated by

user tool,

Code samples W 19
White Paper

// This dll just needs to assign values.

// eg:
strcpy(pUserCredentialStruct->m_szARUserName,"Demo");
pUserCredentialStruct->m_nARNumberOfServers=2;

}//End 'extern "C"

extern "C"

{
__declspec(dllexport) void ARGetSSOServerInformation(ARSSOServerInformation
*pServerInfo)

// The required memory for struct ARSSOServerInformation is allocated by

user tool,
// This dll just needs to assign values.
// eg:
strcpy(pServerInfo[0].m_szARServerName, "ServerName1");
pServerInfo->m_nARTCPNum = 3040;
pServerInfo->m_nARRPCNum = 390622;

strcpy(pServerInfo[1].m_szARServerName, "ServerName2");
}

}//End 'extern "C"

Java (.java file) sample

/*
* Created on Jun 5, 2006
*
* Copyright © 2006 BMC Software, Inc.
* All rights reserved.
*
* This software is the confidential property and proprietary information of
* BMC Software, Inc.
*/
package com.yourcompany.sso;

import java.io.IOException;
import java.util.Map;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.remedy.arsys.session.Authenticator;
import com.remedy.arsys.session.UserCredentials;

/**
* This is an example of a simplistic authenticator. It assumes that your SSO
* solution embeds the credentials in the Http request header as is true in most
* SSO solutions. The key (for extraction of the Http header) of course is
* specific to your solution. What we use here is only for illustration purposes.
*
*/
public class MyAuthenticator implements Authenticator {
//Http header constants specific to your SSO solution. We illustrate here:
private static final String USER = "my-sso-provider-username";
//NOTE: generally passwords are never passed around b/c of security risks.
private static final String PW = "my-sso-provider-password";

20 XIntegrating AR System with single sign-on (SSO) authentication systems

 Integrating AR System with single sign-on (SSO) authentication systems

private static final String AUTH_STRING = "my-sso-provider-SSOtoken";

/**
* @see com.remedy.arsys.session.Authenticator#init(java.util.Map)
*/
public void init(Map cfg) {
//perform any SSO specific initialization here such as encryption set up.
}

/**
* @see com.remedy.arsys.session.Authenticator#destroy()
*/
public void destroy() {
//perform any resource clean up here.
}

/**
* @see
com.remedy.arsys.session.Authenticator#getAuthenticatedCredentials(javax.servlet.http.H
ttpServletRequest, javax.servlet.http.HttpServletResponse)
*/
public UserCredentials getAuthenticatedCredentials(
HttpServletRequest request, HttpServletResponse response)
throws IOException {
String user = request.getHeader(USER);
String pw = request.getHeader(PW);
String authStr = request.getHeader(AUTH_STRING);

//1. check to see if user is auth'd by SSO, ie, has username and token.
if ((user!=null&&user.length()>0) && (authStr!=null&&authStr.length()>0)) {
return new UserCredentials(user.toLowerCase(), pw, authStr);
}
else { //2. user not auth'd; return null.

//embed routing info in response object if necessary.

return null;
}
}

Code samples W 21
White Paper

22 XIntegrating AR System with single sign-on (SSO) authentication systems

Back65712.fm Page 17 Monday, October 16, 2006 12:56 PM
Back65712.fm Page 18 Monday, October 16, 2006 12:56 PM

*65712*
*65712*
*65712*
*65712*
*65712*