This section contains the following topics:
A typical installation of SiteMinder places the Web Servers in the DMZ and the SiteMinder Policy Server inside the firewalls. They communicate with each other using secure, encrypted communications through any intervening firewalls.
Several services supplied by CA Professional Services should be run behind the firewall, such as Advanced Password Services (APS) and Distributed Directory Administration (DDA). These services require access to the underlying user directory, usually LDAP, which should not be exposed within the DMZ for security reasons.
The architecture to accomplish this securely, easily, and with minimal configuration, is implemented by the SmPortal/SmTransact tunnel.
The SiteMinder Agent API toolkit includes a service-processing tunnel called SmTransact. SmTransact allows an arbitrary block of data (limited to 32k in size) to be passed through the firewall to the Policy Server. The Policy Server then passes the data to a library called SmTransact. SmTransact can then pass back up to 32k of response data.
The problem with this system is that it can only process a single service. It is up to the caller(s) to identify the processing that is to occur on the back-end and to write an SmTransact library that can dispatch the service request to the correct application code.
The SmPortal/SmTransact libraries solve this problem. This is a layer, consisting of the SmPortal library on the client and SmTransact on the Policy Server, which allows multiple services to run through the Agent API tunnel. It also provides the following additional capabilities:
These features are primarily of concern to developers.
This kit uses the same libraries that SiteMinder uses to communicate between its agents and the Policy Servers. The same ports are used for this communication and the same encryption methods are used.
If a SiteMinder Web Agent can communicate through the firewall, since SmPortal should be using the same port and such, no additional configuration should be required on the firewall.
This section describes how to install SmPortal and SmTransact.
The SmPortal module consist of these files:
Additional files may be installed to support the SmPortal module. These files include:
All files will be installed using the supplied installation program.
On the SiteMinder Policy Server side, these files must be installed:
Install this file on the SiteMinder BIN directory so that SmPortalTest and SmPortalVfy can be used from the client side to test the configuration.
Note: If APSPing, SmPortalTest and SmPortalVfy are not be used, the APSTransponder and PortalTest libraries are not needed. However, we highly recommend that they be installed anyway.
If the SiteMinder Policy Server is running, you may need to stop it before you can perform the installation.
There is a version of the SmTransact library that is supplied with SiteMinder itself. That version works well with most known SmPortal/SmTransact services, but definitely will not support SmPortalTest and SmPortalVfy as supplied. You should install the later version of SmTransact, if possible. There are no known problems with doing this.
You can install SmTransact on your Policy Server using the supplied installation scripts.
Client applications, often running on a Web Server, make calls to the SmPortal library. SmPortal determines the location of the service provider and how to get there (using SmPortal.cfg). The call is made to SiteMinder communications code and data is passed to the SiteMinder Policy Server.
The SiteMinder Policy Server gets the request from the client and calls code within SmTransact. SmTransact determines the service being requested and loads the proper library (making initialization calls at that time).
SmTransact then calls the proper service code within the service library and returns the data to the caller. SmPortal and SmTransact perform some behind-the-scenes communication to handle large buffers (>32k).
All configuration information for SmPortal is stored in the SmPortal.cfg file. SmPortal looks for this file using several techniques, in this order:
If the file is still not found, an error will occur (it will not use default values).
The SmPortal.cfg file supplied with the kit is not configured to work immediately after installation. It must be modified before communications will work correctly. It must also be modified as each new service is installed.
The following shows the file as it is installed (more or less):
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Servers ;; ;; Each server should have an ip ;; address, specified as: ;; <server>.ip=aaa.bbb.ccc.ddd ;; ;; It *may* also have a port as: ;; <server>.port=44442 ;; ;; It *may* also have a timeout as: ;; <server>.timeout=30000 ;; ;; It *may* also have a minimum number ;; of connections as: ;; <server>.ConnMin=1 ;; ;; It *may* also have a maximum number ;; of connections as: ;; <server>.ConnMax=5 ;; ;; It *may* also have a connection ;; step value as: ;; <server>.ConnStep=1 ;; ;; The entry "Servers" should contain ;; a comma-delimited list of all ;; server names. ;; ;; Entry names are not case-sensitive. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Servers=MyServer MyServer.ip=127.0.0.1 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Agents ;; ;; Each agent should have list of ;; servers, specified as: ;; <agent>.servers=<s1>,<s2>... ;; ;; It must also have a shared secret as: ;; <agent>.secret=xyzzy ;; shared secrets may be encrypted using ;; the APSEncrypt utility (see documentation) ;; ;; It *may* also specify round robining ;; (instead of fail over) as: ;; <server>.RoundRobin ;; ;; The entry "Agents" should contain ;; a comma-delimited list of all ;; Agent names. ;; ;; Entry names ARE case-sensitive. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Agents=ghost ghost.Servers=MyServer ghost.Secret=[NDSEnc-A]6UUYOUf4E6O42CEuYo8H(E4UdyZ ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Services ;; ;; Each service should point to a ;; single agent, specified as: ;; <service>.agent= ;; ;; It *may* also specif<agent>y tracing as: ;; <service>.Trace ;; ;; It *may* also specify debugging as: ;; <service>.Debug ;; ;; The entry "Services" should contain ;; a comma-delimited list of all ;; Service names. ;; ;; Entry names are not case-sensitive. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Services=PortalTest,SmPassword PortalTest.Agent=ghost SmAPS.Agent=ghost
The file is well documented, so that changes can be made with minimal (if any) referral to external documentation.
Any text following a semicolon (;) is considered a comment. Blank lines are ignored.
The file consists of three sections.
The Server Section defines the SiteMinder Policy Servers that are available from this computer.
The Servers= entry contains a comma-delimited list of all of the servers defined for this machine.
Server names are arbitrary. CA Professional Services recommends that the server names match the network name of the Policy Server machine. The name is only used to cross reference values within the configuration file. The name may contain embedded periods and is not case-sensitive.
Any number of servers may be defined in this section, but each server must have at least one entry following the Servers entry:
<servername>.ip=<IP-address>
This entry defines the IP address used to get to the specified Policy Server. The IP address specified here must be the one used to access the Policy Server from the server running the SmPortal code. Thus, if address translation is in effect at the firewall, the address may not match the actual address of the Policy Server.
The easiest way to determine this address at most sites is to open the SiteMinder Web Agent Management Console on the system and examine the address of the Primary SiteMinder Policy Server. If the Web Agent communicates properly with the SiteMinder Policy Server, then this is the correct address.
The <servername> portion of the setting name must match the name listed in the Servers setting.
<server>.port=CA Portal
This setting may be used to change the port used to communicate with the Policy Server. The default is port 44442. It must match the port used by the Authentication Service on the SiteMinder Policy Server.
<server>.timeout=<timeout in milliseconds>
This allows the administrator to override the timeout for the specified server. The default is 30000 (30 seconds). This is a reasonable timeout and should not, in general, be changed.
<server>.ConnMin=<minimum connections>
This setting allows the specification of the minimum number of connections to the server that SmPortal should initialize. The default value of one should be used in almost all cases. This setting is intended for use by applications that require multiple connections to a Policy Server.
<server>.ConnMax=<maximum connections>
This setting allows the specification of the maximum number of connections to the server that SmPortal should initialize. The default value of one should be used in almost all cases. This setting is intended for use by applications that require multiple connections to a Policy Server.
<server>.ConnStep=<connection step value>
If the minimum and maximum connections are set, this value specifies the stepping value that SmPortal should use between the minimum and maximum values. For example, if the minimum value is one and the maximum value is 25, the stepping value might be five. This would cause SmPortal to increment the number of connections by five each time that it runs out of connections. The default value of one should be used in almost all cases. This setting is intended for use by applications that require multiple connections to a Policy Server.
The Agent section tells SmPortal which agents exist and the servers that know about them.
The Agents= entry contains a comma-delimited list of all of the agents which may be used from this machine.
Agent names are not arbitrary. Each must match an Agent configured on a Siteminder Policy Server. The name is case-sensitive. Typically, the same agent names are used for both services and the resident Web Agent, but this is not required.
Any number of Agents may be listed immediately after the Agents line. Each Agent must be defined using the following two lines:
<agent>.Servers=<serverlist> <agent>.Secret=<shared secret>
The first line defines the servers on which this agent is defined. The server list contains a comma-delimited list of servers that know about this Agent. Each server so referenced must be defined in the server section.
The order in which servers are defined is significant. By default, SmPortal will attempt to contact servers in the order listed here. Multiple servers are used for fault-tolerance; if a server cannot be contacted, the next server in the list is used. Any number of servers can be listed.
The Secret line defines the shared secret used between the Agent and the Policy Server. This must be the same secret configured on the Policy Server(s) for the Agent.
Secrets can be stored in either plain text or in encrypted format. If the secret is stored in plain text and this is a problem, define specific agents for services, thus hiding the shared secret used by the Web Agent. Since no policies need to be created in order to run the services through the tunnel (though they may be required to access the application through the Web Agent), security is maintained.
To store the secret in encrypted format, use the APSEncrypt utility to encrypt the shared secret, then copy the encrypted value (output from APSEncrypt) into the <agent>.Secret line in SmPortal.cfg.
By default, if multiple servers are specified for an agent, the servers will be used in failover mode (the first server used unless it is unavailable, in which case, SmPortal will use the second server, and so on).
To specify that the server list is to be used in round robin format, use the following setting:
<agent>.RoundRobin
SmPortal cannot do true round-robining because each application that uses SmPortal is a completely independent instance. Instead, SmPortal will simulate round-robining by randomly rotating the list of servers, then using the resulting list as though failover mode were specified. This technique provides the same results as true round-robining.
The Service section defines the services that can use SmPortal and what Agent configuration each should use.
The Services= entry contains a comma-delimited list of all services that may be used from this system.
Each application or API that uses a service has its service name encoded within it. See the documentation for the service itself to determine the name of the service. Note that the name may not correspond to the actual product name.
After the Services= entry, each service is identified by a single line that define the Agent to be used by that service.
<service>.Agent=<agent>
The value for the agent must correspond to an Agent name defined in the previous section.
The service name for SmPortalTest is PortalTest and should already be listed in SmPortal.cfg.
Some applications may support qualified service names. For example, SmPortalTest allows multiple definitions of the PortalTest service within the configuration file. Each entry must be qualified as in:
Qualifier1.PortalTest.Agent=ghost
AnotherInstance.PortalTest.Agent=ranger
Qualifiers allow the same service to run on multiple servers, yet still be addressable independently. In the PortalTest example, it allows the SmPortalTest application to select from several possible configurations (targets) for the PortalTest service.
If a service name is to be qualified, all optional settings should be qualified as well.
If a qualified service name is requested by an application, but no qualifiers match for that service, the unqualified settings for the same service will be used (if configured).
Not all applications support qualified services.
<service>.Trace
This setting turns on trace logging for the service. The back-end service library will be notified that tracing is requested. The actual tracing performed is up to the service itself and will vary. All tracing is written to the SiteMinder console log.
Trace and debug logging may also be turned on within the code. If so, these settings will have no effect.
<service>.Debug
This setting turns on debug logging for the service. The back-end service library will be notified that debug tracing is requested. The actual logging performed is up to the service itself and will vary, though SmTransact performs some debug logging as well, if this setting is turned on.
Trace and debug logging may also be turned on within the code. If so, these settings will have no effect.
Two utilities may be supplied with the kit that can be used to verify a configuration.
The SmPortalTest (SmPortalTest.exe on Windows) can be used to verify that SmPortal can communicate properly with a SiteMinder Policy Server. SmPortalTest communicates through the tunnel to the PortalTest service, running on a Policy Server.
SmPortalTest takes each of its command line arguments and transmits them to PortalTest. PortalTest merely reverses the passed string and returns it.
A typical execution, on a properly configured site, might look like:
>SmPortalTest abc Returned (4 bytes): "cba"
The string abc is passed and cba is returned. This indicates proper configuration.
A failure might be indicated thus:
>SmPortalTest abc Returned Error Code = -18 Message: "Unable to establish server's IP address"
For suggested solutions to possible error codes, see Connectivity Problems.
The PortalTest library must be installed on each server that you wish to test a tunnel to. Note that the SmTransact library as supplied with SiteMinder does not include a version of PortalTest.
We recommend that each agent configuration be tested using SmPortalTest. This is done by configuring the PortalTest service for each agent (in SmPortal.cfg), in turn, then executing SmPortalTest to make sure that that agent's configuration is valid.
Most arguments passed to SmPortalTest will be sent to the PortalTest library as stated above. However, SmPortalTest recognizes some special command line arguments.
The available arguments will be displayed when -? appears on the command line.
To specify a language other than English to use for error messages, use the ‑L option to specify the ISO code for the language, as in:
SmPortalTest -LFR
To specify a country other than the US to use for error messages, use the ‑C option to specify the ISO code for the country, as in:
SmPortalTest -CCA
Normally, SmPortalTest creates a single connection to the Policy Server and issues each service request to PortalTest on the same connection. This option tells SmPortalTest whether or not each service request (transaction) should be sent on the same connection or on a separate connection.
Isolation can be turned on or off and will affect all transactions appearing after the setting. For example,
SmPortalTest -I+ abc def -I- ghi jkl
will cause SmPortalTest to isolate the abc and def transactions. The ghi and jkl will be processed on the same connection.
There are three arguments that are used for automated testing. The -X option specifies the number of iterations to be used (the default is infinite). The -S option specifies the number of seconds to wait between each transaction and the -T option specifies that automated testing is to be used and can specify the size of each transaction. When using Automated Testing, the isolation setting is honored.
For example,
SmPortalTest -T
will perform automated testing using the default transaction size of 512 bytes. The test will be continued until Control-C is pressed. SmPortalTest will not wait between transactions. Transactions will not be isolated (since this is the default).
SmPortalTest -I+ -X15 -S3 -T256
This command line will perform 15 (the -X option) isolated transactions (the -I+ option), 15 seconds apart (the -S option), using a 256 byte buffer.
There is a 1K limit to the automated testing buffer at this time.
The -Q option can be used to qualify the service name used when referencing the SmPortal.cfg file. If -Q is used, it should be immediately followed by the desired qualifier.
SmPortalTest -Qghost abc -Qranger def
If -Q is used without a qualifier, no qualifier will be used.
SmPortalTest -Qghost abc -Qranger def -Q ghi
SmPortalVfy is a new utility supplied with SmPortal version 5.0 that verifies the entire SmPortal.cfg file. It will only work properly if SmTransact version 5.0 (or later) is installed on the Policy Server.
SmPortalVfy is typically invoked with no command line arguments. It will test each setting in the default SmPortal.cfg file and report the results.
The verification process consists of two phases. First, the utility cross checks all of the configuration to ensure that the settings make sense within the file. If any problems are detected, they are reported and the verification process stops.
The second phase actually tests each setting within the file by attempting to communicate with the component. SmPortalVfy will attempt to communicate with each server, each agent's server (as the agent), and each service (as the agent for each of the agent's defined servers) defined within the file.
SmPortalVfy may not detect that a server is unavailable during its initial checking. This is normal and depends on a number of factors. If a server is unavailable, it will definitely be detected when the agents are checked against that server.
Any error during the communications phase will terminate processing.
SmPortalVfy supports one optional argument that specifies a path to SmPortal.cfg. This can be used to verify a new SmPortal.cfg file before putting it into production.
APSPing is a new utility supplied with SmPortal version 5.0 that can test the connectivity to a single policy server, a service on that server, or an SmTunnel function housed by a service. It will only work properly if the (new) APSTransponder library is installed on the Policy Server.
|
Copyright © 2013 CA.
All rights reserved.
|
|