The ATG product suite includes a set of Web services that you can use to make calls to Dynamo from non-ATG applications. The services provided with ATG Personalization and ATG Scenarios allow you to retrieve and change user profile information, perform content targeting operations, and send profile-related messages to the Dynamo Messaging System. For example, users can log into an ATG application and perform profile updates; you can retrieve the profile ID of a given user; you can display content items that are tailored to the current user; and you can fire an event message if a user views a specific piece of content.
Many of the se Web services were designed to have the same functionality as their non-Web service counterparts. For example, standard Profile Form Handler operations have parallel Web service operations. This behavior helps you reproduce any code extensions that you have made to non-Web service classes.
This chapter contains the following information:
The default Web services for Personalization and Scenarios are packaged in the DPS.WebServices
module in the ATG Personalization layer. The code that is called for these Web services is located in the DAF, Personalization, or Scenarios layer, depending on the service.
For information on how to include this module in your application, refer to the ATG Installation and Configuration Guide.
The user profiling Web services provided with the ATG product suite allow you to access the ATG profile repository from a non-ATG application. You can use these Web services to perform login and logout operations, create new profiles and change existing ones, and manage passwords.
This section contains the following topics:
Note: In the sections that follow, some Web service descriptions include URLs with the variables hostname
:
port
. For hostname
, use the name of the machine running your application. For port
, enter the number of the port that your application server uses to handle HTTP requests on that machine.
The /atg/userprofiling/ProfileServices
component (class atg.userprofiling.ProfileServices
) manages many of the Web service functions related to user profiling. Note that some of these functions mimic the behavior of standard ATG profile form handlers; this behavior is designed to help you reproduce any profile form handler custom code as extensions of out-of-the-box Web services.
The following list shows the properties of the ProfileServices
component.
transactionManager
Type:
javax.transaction.TransactionManager
The service that manages any transactions used to execute repository methods on this instance.
Default:
/atg/dynamo/transaction/TransactionManager
(set in DPS module)mappingManager
Type:
atg.repository.xml.ItemDescriptorMappingManager
The component that manages mapping files based on repository item descriptor name combinations. Any methods that return repository items consult this service to retrieve the mapping files to use when transforming these items into XML. Note that this behavior assumes the
useDefaultMappingFiles
property is set to true.Default:
/atg/repository/xml/ItemDescriptorMappingManager
(set in DPS module)xmlGetService
Type:
atg.repository.xml.GetService
The service that turns repository items into XML.
Default:
/atg/repository/xml/GetService
(set in DPS module)xmlAddService
Type:
atg.repository.xml.AddService
The service that adds repository items in XML format to a repository.
Default:
/atg/repository/xml/AddService
(set in DPS module)xmlUpdateService
Type:
atg.repository.xml.UpdateService
The service that takes repository items in XML format and updates them in their corresponding repositories.
Default:
/atg/repository/xml/UpdateService
(set in DPS module)profileTools
Type:
atg.userprofiling.ProfileTools
The profile tools service that provides access to common profiling functions, as well as access to other profile components such as the
PropertyManager
andProfileRepository
.Default:
/atg/userprofiling/ProfileTools
(set in DPS module)updateEventListeners
Type:
atg.userprofiling.ProfileUpdateListener[]
An array of
ProfileUpdateListeners
that are notified when a profile is updated. Note that thegenerateUpdateEvents
property must be set to true for this behavior to occur.Default:
/atg/userprofiling/ProfileUpdateTrigger
(set in DPS module)generateLoginEvents
Type: boolean
If true, the
LoginUser
Web service fires login events after a user has been successfully logged in.Default: true (set in DPS module)
generateUpdateEvents
Type: boolean
If true, the
UpdateUser
Web service fires update events after a user profile has been successfully updated.Default: true (set in DPS module)
generateRegisterEvents
Type: boolean
If true, the
CreateUser
Web service fires register events after a user profile has been successfully created.Default: true (set in DPS module)
generateLogoutEvents
Type: boolean
If true, the
logoutUser
service fires logout events after a user has been successfully logged out.Default: true (set in DPS module)
expireSessionOnLogout
Type: boolean
Behaves the same way as the
expiresSessionOnLogout
property in theProfileFormHandler
class. See the description of thehandleLogout
method in Profile Form Handlers.Default: true (set in DPS module)
usingLDAPProfile
Type: boolean
Behaves the same way as the
usingLDAPProfile
property in theProfileFormHandler
class. It indicates whether the profile in use is stored in an LDAP directory.Default: false (set in DPS module)
useDefaultMappings
Type: boolean
If true, methods that return
Repo2Xml
items map properties according to the default mappings configured in theItemDescriptorMappingManager
(unless the Web service calls a variation of a method that takes a mapping file location as an argument).Default: true (set in DPS module)
logoutProfileType
Type: String
Behaves the same way as the
logoutProfileType
property in theProfileFormHandler
class. It specifies the item descriptor type of the profile defaulted to when the current user logs out.Default:
user
(set in DPS module)createProfileType
Type: String
Behaves the same way as the
createProfileType
property in theProfileFormHandler
class. It specifies the item descriptor type of the profile created when a new profile is added to the repository.Default:
user
(set in DPS module)loginProfileType
Type: String
Behaves the same way as the
loginProfileType
property in theProfileFormHandler
class. It specifies the item descriptor type of the profile accessed when a user logs in.Default:
user
(set in DPS module)propertiesToCopyOnLogin
Type: String[]
Behaves the same way as the
propertiesToCopyOnLogin
property in theProfileFormHandler
class. It specifies the property values to copy from the anonymous profile to the persistent profile when a user logs in.Default: null (set in DPS module)
propertiesToAddOnLogin
Type: String[]
Behaves the same way as the
propertiesToAddOnLogin
property in theProfileFormHandler
class. It specifies the properties to add from the anonymous profile to the persistent profile when a user logs in.Default:
scenarioInstances
,slotInstances
(set in DSS module)maxAuthenticationWait
Type: long
Indicates how long a password encryption conversation is allowed to last, which is the length of time between calls to
getPasswordHashKey
andloginUser
. If the length of time between these two calls exceeds themaxAuthenticationWait
property value, the login is invalid. Note that this behavior assumes the login attempt is encrypted (in other words, thatpIsPasswordEncrypted
is true for theloginUser
call).Default: 30000 (30 seconds) (set in DPS module)
badPasswordDelay
Type: long
Behaves the same way as the
badPasswordDelay
property in theProfileFormHandler
class. It specifies the number of milliseconds to wait before proceeding after a user submits a password that fails authentication.Default: 1000 (1 second) (set in DPS module)
profilePath
Type: String
The component path of the
Profile
component.Default:
/atg/userprofiling/Profile
(set in DPS module)requestLocalePath
Type: String
The component path of the
RequestLocale
component.Default:
/atg/dynamo/servlet/RequestLocale
(set in DPS module)allowEncryptedPasswords
Type: boolean
If true, allows login attempts that use passwords encrypted on the client. Even if this property is true, the
canClientEncryptPasswords()
method still needs to return true to verify that the application itself can handle passwords encrypted in this way.Default: true (set in DPS module)
The GetProfileId
Web service finds the profile that matches the login supplied by the method call and returns its profile ID. For an example of how to invoke this Web service in a client application, see Example: Using the GetProfileId Web Service in an Axis Client.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String |
Output | String |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
getProfileId Method
The GetProfileId
Web service calls the getProfileId
method in the underlying atg.userprofiling.ProfileServices
implementation.
The getProfileId
method does the following:
Calls
ProfileTools.getItem()
with the given login.Returns the ID of the found item or null if no item exists with that login.
Security Recommendation
It is recommended that you restrict the ability to call the GetProfileId
Web service to administrative users.
The GetProfile
Web service finds the profile that matches the supplied profile ID and returns it as a RepositoryItem
in XML form (a Repo2Xml
item). For more information, see Returning RepositoryItems as Repo2Xml Items. You can configure a mapping file for this XML item on the component that contains the getProfileId
method. (It is recommended, for example, that you define the mapping file so that the password property is omitted when the item is returned.)
By default, the profile repository that the GetProfile
Web service accesses is the /atg/userprofiling/ProfileAdapterRepository
(specifically, the user
item descriptor).
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String |
Output | String |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
getProfile Method
The GetProfile
Web service calls the getProfile
method in the underlying atg.userprofiling.ProfileServices
implementation. The method invokes getItem
on the profile repository and transforms the result into a Repo2Xml
item. An HTTP request is not required for this method.
Security Recommendation
It is recommended that you restrict the ability to call the GetProfileId
Web service to administrative users.
The LoginUser
Web service authenticates the identity of the user for whom the service was called, returning the user’s profile ID if authentication is successful.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String |
Output | String |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
loginUser Method
The LoginUser
Web service calls the loginUser
method in the underlying atg.userprofiling.ProfileServices
implementation. The loginUser
method behaves the same way as the handleLogin
method in the ProfileFormHandler
(see The ProfileForm Class). Note that loginUser
should be called only in the context of an HTTP request; otherwise an error occurs.
loginUser
takes the supplied login name and password and uses them to locate a valid profile. To do this, it calls the following methods:
preLoginUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
doLoginUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
postLoginUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
The preLoginUser
and postLoginUser
methods are similar to the ProfileFormHandler
’s preLoginUser
and postLoginUser
methods, which are stubs designed to allow subclasses to control login logic before and after the login process. You can write extensions to this code by overriding these methods with your own custom subclasses.
Unlike the ProfileFormHandler
, the loginUser
Web service immediately propagates to the caller any errors that occur during processing. Errors are not stored and shown to the user because the caller in this case is an RPC client that does not have access to a request/response pair. (The ProfileFormHandler
, by contrast, expects to have its errors shown on an HTML page where the user can correct them and resubmit.) This error-handling behavior is used by all profile-related Web services that mimic ProfileFormHandler
functionality.
The loginUser
method acts as follows:
If
pIsPasswordEncrypted
is true, theloginUser
method checks to see if a valid password encryption conversation has occurred in this session. If not, aServletException
is thrown.loginUser
calls thepreLoginUser
method, which checks that the session associated with the current profile is not transient and then does the following:If the current profile’s login does not match the login that was passed to the Web service, the current profile is logged out, and its session is expired.
If the login and password given to the Web service match those in the current profile, it is assumed that the same user is logging in again. In this case, an exception is thrown so that login events and profile cookies are not resent. In addition, the
securityStatus
of the profile is reset to the loginsecurityStatus
(ifsecurityStatus
is enabled).If the password passed to the Web service does not match the password stored for the given login name, a
ServletException
is thrown.
loginUser
callsdoLoginUser
, which attempts to authenticate the user based on the given credentials. It forward-hashes the stored password for the given user with ahashKey
initialized during the password encryption conversation and compares it to the password argument. If this check succeeds, theRepositoryItem
for that user is set as the current profile’s data source, and repository properties are copied and/or added from the guest user’s profile to the authenticated user’s profile.The profile ID is returned for the user who just logged in.
If the password encryption comparison fails, indicating that either the login name or the password was invalid, null is returned by
doLoginUser
.The
loginUser
method calls thepostLoginUser
method, which sends a login event if configured to do so (setgenerateLoginEvents
to true in theProfileServices
component). It also sends profile cookies if necessary, sets the security status for the logged-in profile, and changes the request locale to reflect the logged-in profile’s locale.
Security Recommendation
Users are not authenticated before the LoginUser
Web service is called, so there is no specific security policy recommendation for this service.
The LogoutUser
Web service attempts to log out the user for whom the logoutUser
method is called (the user associated with the current session).
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | None |
Output | None |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
logoutUser Method
The LogoutUser
Web service calls the logoutUser
method in the underlying atg.userprofiling.ProfileServices
implementation. The logoutUser
method behaves the same way as the handleLogout
method in the ProfileFormHandler
(see The ProfileForm Class). Note that logoutUser
should be called only in the context of an HTTP request; otherwise an error occurs.
logoutUser
invokes the following methods:
preLogoutUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
doLogoutUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
postLoginUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
These methods are similar to the ProfileFormHandler
’s preLogoutUser
, handleLogout
, and postLogoutUser
methods.
The logoutUser
method acts as follows:
Calls
preLogoutUser
, which sets up a logout event and revokes the current user’s identity.Calls
doLogoutUser
.Calls
postLogoutUser
, which fires a logout event and expires the current session if configured to do so. (You can control this behavior through thegenerateLogoutEvents
andexpireSessionOnLogout
properties in theProfileServices
component.)
Security Recommendation
It is recommended that you restrict the ability to call the LogoutUser
service to appropriate users. For example, you would generally not want anonymous or guest users to be able to invoke LogoutUser
.
The CreateUser
Web service attempts to create a new profile from the information in the input ProfileAsXML
String, which is a Repo2XML
item. The profile ID for the new profile is returned.
Any password present in the ProfileAsXML
argument must be cleartext, so it is recommended you always use a secure connection to call this service.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String |
Output | String |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
createUser Method
The createUser
Web service calls the createUser
method in the underlying atg.userprofiling.ProfileServices
implementation. The createUser
method behaves the same way as the handleCreate
method in the ProfileFormHandler
(see The ProfileForm Class). Note that createUser
should be called only in the context of an HTTP request; otherwise an error occurs.
createUser
invokes the following methods:
preCreateUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
doCreateUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
postCreateUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
These methods are similar to the ProfileFormHandler
’s preCreateUser
, createUser
, and postCreateUser
methods.
The createUser
method acts as follows:
Calls
preCreateUser
.Calls
doCreateUser
, which uses aRepo2Xml
AddService
to add the given item to the repository. If successful, the item is then set as the data source for the current profile. Any password present in the given item is also encrypted for storage. (As mentioned above, it is expected that passwords given in thepProfileAsXML
are cleartext.)Calls
postCreateUser
, which sets profile cookies if required to do so.postCreateUser
also fires a register event if you set thegenerateRegisterEvents
to true in theProfileServices
component.
Security Recommendation
The user has no credentials before the CreateUser
Web service is called, so there is no specific security policy recommendation for it.
The UpdateUser
Web service attempts to change a profile using information passed in as the ProfileAsXML
argument (a Repo2XML
item).
Note: Do not use this service for updating passwords. If a password property were included in the Repo2Xml
item for this ProfileAsXML
argument, the value would be persisted as it appeared in the file; the password string would not be encrypted, resulting in invalid login attempts for the user in the future. To change a password, use the setPassword
Web service instead.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String |
Output | None |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
updateUser Method
The updateUser
Web service calls the updateUser
method in the underlying atg.userprofiling.ProfileServices
implementation. The updateUser
method behaves the same way as the handleUpdate
method in the ProfileFormHandler
(see The ProfileForm Class). Note that updateUser
should be called only in the context of an HTTP request; otherwise an error occurs.
updateUser
invokes the following methods:
preUpdateUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
doUpdateUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
postUpdateUser(DynamoHttpServletRequest pRequest, DynamoHttpServletResponse pResponse)
These methods are similar to the ProfileFormHandler
’s preUpdateUser
, updateUser
, and postUpdateUser
methods.
The updateUser
method acts as follows:
Calls
preUpdateUser
, which sets up aProfileUpdateEvent
but does not fire it.Calls
doUpdateUser
, which uses aRepo2Xml
update service to update the givenpProfileAsXML
.Calls
postUpdateUser
, which may revoke profile cookies if the user’sautoLogin
property changes from true to false. It also fires aProfileUpdateEvent
if configured to do so (setgenerateUpdateEvents
to true in theProfileServices
component).
Security Recommendation
Apply the atg.userprofiling.ProfileAsXMLOwnerPolicy
to this service. This security policy verifies that the user associated with the current session matches the user whose profile is being updated. The functional name (xmlProfileOwnerOperation
) differs from the profileOwnerOperation
used by other services that are based on profile ownership because the security argument in this service is a Repo2Xml
item rather than a profile ID. For more information, see ProfileAsXMLOwnerPolicy.
The SetPassword
Web service changes the password of the user specified by the ProfileId
argument. It requires the user’s current password for security reasons. The service checks the value of the supplied password (OriginalPassword
) against the value stored for this user in the profile repository. If the values match, the password is changed to the new password.
Do not encrypt OriginalPassword
or NewPassword
. Both are expected to be cleartext as they are forward-hashed for comparison with the stored password value.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String |
Output | None |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
setPassword Method
The SetPassword
Web service calls the setPassword
method in the underlying atg.userprofiling.ProfileServices
implementation. Note that setPassword
should be called only in the context of an HTTP request; otherwise an error occurs. The method does the following:
Calls
preSetPassword
.Calls
doSetPassword
, which compares the password currently stored for the user (specified by the supplied profile ID) with the givenpOldPassword
. If the check succeeds, the user’s password is set topNewPassword
.Calls
postSetPassword
.
Security Recommendation
Apply the atg.userprofiling.ProfileOwnerPolicy
to this Web service. This policy requires that the ProfileId
argument match the profile ID of the user who is calling the method. This behavior ensures that a password can be changed only by the person who owns the profile. For more information, see ProfileOwnerPolicy.
The SetContactInfo
Web service sets or changes the contact information of the user specified by the ProfileId
argument to the value of the supplied ContactInfoAsXML
item. If the given ContactInfoAsXML
represents an item that does not yet exist in the repository, it is added. This service assumes that the User item descriptor for your ProfileAdapterRepository
component defines a single-valued address property.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String |
Output | None |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
setContactInfo Method
The SetContactInfo
Web service calls the setContactInfo
method in the underlying atg.userprofiling.ProfileServices
implementation. This method attempts to set the contact information of the user who is specified by the profile ID to the given value, which is represented as a Repo2Xml
item. Use the PropertyManager.contactInfoPropertyName
to specify the property where contact information is stored in your profile repository configuration. This property should be of type atg.repository.RepositoryItem
.
The setContactInfo
method acts as follows:
Checks that the given
pProfileId
resolves to a valid profile.Takes the
pContactInfoAsXML
and uses it to get or create aRepositoryItem
.Sets the contact information property of the user represented by
pProfileId
to theRepositoryItem
returned by the previous step.
Security Recommendation
Apply the atg.userprofiling.ProfileOwnerPolicy
to this Web service. This policy requires that the ProfileId
argument match the profile ID of the user who is calling the method. This behavior ensures that contact information can be changed only by the person who owns the profile. For more information, see ProfileOwnerPolicy.
The SetLocale
Web service changes the locale property of the user represented by the specified profile ID to the value of the LocaleName
argument. If the profile ID matches the ID of the user associated with the current session, the RequestLocale
component is also changed appropriately.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String |
Output | None |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
setLocale Method
The SetLocale
Web service calls the setLocale
method in the underlying atg.userprofiling.ProfileServices
implementation. This method attempts to set the locale of the user who is specified by the profile ID to the given value. Use the PropertyManager.localePropertyName
to specify the property where the locale is stored in your profile repository configuration.
The setLocale
method acts as follows:
Checks that the given
pProfileId
resolves to a valid profile.If the locale property exists, sets the locale property of the given user to
pLocaleName
.If the user whose locale is being changed is also the user associated with the current session, the
RequestLocale
component is also changed to reflect the new locale.
Security Recommendation
Apply the atg.userprofiling.ProfileOwnerPolicy
to this Web service. This policy requires that the ProfileId
argument match the profile ID of the user who is calling the method. This behavior ensures that locale information can be changed only by the person who owns the profile. For more information, see ProfileOwnerPolicy.
The CanClientEncryptPasswords
Web service is used as part of the optional client-side encryption feature (see Using Client-Side Password Encryption) that you can use with the LoginUser
Web service. It is a utility service that checks to see if a client is configured and able to encrypt passwords for sending via an ATG Web service. Currently, only the LoginUser
Web service can handle passwords encrypted by the client.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | None |
Output | boolean |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
canClientEncryptPasswords Method
The CanClientEncryptPasswords
Web service calls the canClientEncryptPasswords
method in the underlying atg.userprofiling.ProfileServices
implementation.
The canClientEncryptPasswords
method checks that all of the following are true:
The
allowEncryptedPasswords
property ofProfileServices
is set to true.The password hasher configured for the application supports temporary encryption keys.
The password hasher configured for the application is supported.
In all other cases, this method returns false.
For more information on the way this method is used, refer to Using Client-Side Password Encryption.
Security Recommendation
You can apply any appropriate security policy to the CanClientEncryptPasswords
Web service. As this service is used in conjunction with the LoginUser
service, it is suggested that you use the same security policy for both.
The GetPassWordHashKey
Web service is used as part of the optional client-side encryption feature (see Using Client-Side Password Encryption). It returns a temporary hashKey
used by the client to encrypt a password for a single authentication call. The client forward-encrypts the password with this hash key. The server then stores the hash key in the current session so you do not have to return it to the LoginUser
service.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | None |
Output | String |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
getPasswordHashKey Method
The GetPasswordHashKey
Web service calls the getPasswordHashKey
method in the underlying atg.userprofiling.ProfileServices
implementation.
The getPasswordHashKey
method acts as follows:
Returns null if not called in the context of a request.
Sets up session attributes to indicate that a password encryption conversation has started.
If the password hasher does not support hash keys, this method returns null (in other words,
PasswordHasher.getPasswordHashKey()
returns null). If hash keys are supported, the method returns the value provided by the password hasher and sets that hash key as a session attribute of the current session.
For more information on the way this method is used, refer to Using Client-Side Password Encryption.
Security Recommendation
You can apply any appropriate security policy to the GetPasswordHashKey
Web service. As this service is used in conjunction with the LoginUser
service, it is suggested that you use the same security policy for both.
The GetPasswordHashAlgorithm
Web service is used as part of the optional client-side encryption feature (see Using Client-Side Password Encryption). It returns the name of the algorithm that the containing application on the server uses to hash passwords, for example MD5, SHA, or SSHA. (Note that only MD5 is currently supported.) Along with a hashKey
, this service allows the client to encrypt the password and pass it to the LoginUser
or CreateUser
Web service over unsecured transport mechanisms.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | None |
Output | String |
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
getPasswordHashAlgorithm Method
The GetPasswordHashAlgorithm
Web service calls the getPasswordHashAlgorithm
method in the underlying atg.userprofiling.ProfileServices
implementation. It is assumed that you call canClientEncryptPasswords()
before calling this method, or that you know that this application can encrypt passwords.
The getPasswordHashAlgorithm
method acts as follows:
If the
PasswordHasher
used for this application is not supported, thegetPasswordHashAlgorithm
method throws aServletException
. (Note that only MD5 is currently supported.)Returns the password-hashing algorithm used for this application. Each password hasher has a unique way of encrypting passwords, so clients that attempt password encryption need to know the procedure that their password hasher uses.
Security Recommendation
You can apply any appropriate security policy to the GetPasswordHashAlgorithm
Web service. As this service is used in conjunction with the LoginUser
service, it is suggested that you use the same security policy for both.
One content targeting Web service, RecommendContent
, is provided by default with the ATG product suite. It allows you to use a content targeter (created using the Personalization module) or slot (created in the Scenarios module) to display text or images that are appropriate for the person associated with the current user profile.
This section contains the following topics:
Note: In the sections that follow, some Web service descriptions include URLs with the variables hostname
:
port
. For hostname
, use the name of the machine running your application. For port
, enter the number of the port that your application server uses to handle HTTP requests on that machine.
The /atg/targeting/TargetingServices
component (class atg.targeting.TargetingServices
) manages functions related to the Web services that perform targeting operations (by default, the RecommendContent
Web service). The component has the following properties:
xmlGetService
Type:
atg.repository.xml.GetService
The service that turns
RepositoryItems
into XMLDefault:
/atg/repository/xml/GetService
(set in DPS module)mappingManager
Type:
atg.repository.xml.ItemDescriptorMappingManager
The component that manages mapping files based on repository item descriptor name combinations. Any methods that return repository items consult this service to retrieve the mapping files to use when transforming these items into XML. Note that this behavior assumes the
useDefaultMappingFiles
property is set to true.Default:
/atg/repository/xml/ItemDescriptorMappingManager
(set in DPS module)useDefaultMappings
Type: boolean
If true, methods that return
Repo2Xml
items use the default mappings configured in theItemDescriptorMappingManager
(unless the Web service calls a variation of a method that takes a mapping file location as an argument).Default: true (set in DPS module)
For more information on using mapping files to manage Repo2Xml
items, refer to Returning RepositoryItems as Repo2Xml Items.
The RecommendContent
Web service performs a content targeting operation, taking a slot or targeter path as input and returning n content items, where n is the value of the given howMany
parameter. The content is returned in XML form as an array of Repo2Xml
items. A value of -1 for the howMany
parameter indicates that there is no limit to the number of returned results.
If called in the context of an HTTP request, this service can resolve both request- and session-scoped targeter and slot components. If no HTTP request is present, the service can resolve only globally-scoped components.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters | String int int |
Output |
|
Nucleus Component |
|
Method |
|
Executes within a session | Yes |
Security |
|
executeRepositoryTargeter Method
The RecommendContent
Web service calls the executeRepositoryTargeter
method in the underlying atg.targeting.TargetingServices
implementation. This method does the following:
Resolves the given
pTargeterPath
by attempting to use the current request as aNameResolver
.If a slot or targeter is found, the
target()
method is called.pStartingIndex
andpMaxResults
are passed in as arguments.Any results that are returned are changed into
Repo2Xml
items and passed back as a String.
Security Recommendation
There is no specific security policy recommendation for the RecommendContent
Web service; it is assumed that you want all users to whom the targeter or slot applies to be able to call this service.
The ATG product suite includes some Web services that you can use to send JMS messages to the Dynamo Messaging System. The default services send PageVisit
and Clickthrough
event messages, which you can use in a number of ways in your ATG application – for example, you can set up a scenario that is triggered whenever a PageVisit
message with specific parameters is received.
This section contains the following topics:
Note: In the sections that follow, some Web service descriptions include URLs with the variables hostname
:
port
. For hostname
, use the name of the machine running your application. For port
, enter the number of the port that your application server uses to handle HTTP requests on that machine.
The default Web services that send JMS messages do so by calling the receiveObjectMessage()
method exposed by the /atg/dynamo/messaging/MessagingImporter
component. The MessagingImporter
component is an instance of class atg.dms.patchbay.MessageImporter
, which is part of the Web service infrastructure in the DAF layer.
The receiveObjectMessage()
method takes three parameters:
the message object
a String indicating the
JMSType
of the messagea String indicating the Patch Bay port name to use
The Web services that call this method take a message object as their input parameter.
For more information, refer to
JMS Web Services in the ATG Web Services and Integration Framework Guide.
The ContentViewed
Web service sends a PageVisitMessage
to Patch Bay.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters |
|
Output | None |
Nucleus Component |
|
Method |
Note that for the default
|
Executes within a session | Yes |
Security |
|
Setting PageVisit Message Properties for a Web Service
When PageVisit
JMS messages are sent within an ATG application rather than to an ATG application from a Web service, the values of various message properties are determined by the PageEventTrigger
component on the ATG server. When you send these messages through a Web service, however, the PageEventTrigger
is not available, and you must set them explicitly on the PageVisit
object created by the client application.
Note that setting these values incorrectly will prevent any scenarios that are waiting for these messages from being fired.
Use the same settings for the PageVisit
message properties that you would use for a message sent within an ATG application, with the following important exception: use the path
property rather than scenarioPathInfo
property to specify the path of the page that was visited. This behavior is necessary because only the PageEventTrigger
contains the necessary logic for specifying the correct value for scenarioInfoPath
.
Important: When you set up a scenario to watch for this event, do not use the document picker (Choose document…
) to select the page to include in the Visits element; pages specified this way automatically use the scenarioInfoPath
property. Instead, use the whose path
or with Dynamo path
option in the element to specify the path to the page, and make sure that the value you enter matches the value that you send in the message from the Web service. Both of the following examples are valid ways to specify the correct path in the scenario element:
Visits a page whose path is /en/index.jsp
Or
Visits a page with Dynamo path /en/index.jsp
For pages that are outside the Dynamo document root (the page is part of a non-DAS J2EE application) make sure the path
property includes the application context root.
For more information on the PageVisit
message, refer to PageVisit Event.
The ContentConsumed
Web service sends a ClickThroughMessage
to Patch Bay.
EAR file |
|
WAR file |
|
Context root |
|
Servlet |
|
Web Service URL |
|
WSDL URL |
|
Web Service Class |
|
Input Parameters |
|
Output | None |
Nucleus Component |
|
Method |
Note that for the default
|
Executes within a session | Yes |
Security |
|
Refer to ClickThrough Event for information on the properties to set in the ClickThrough
message object.
The following example shows how you could retrieve a profile ID from the ATG system by using the GetProfileId
Web service in an Apache Axis client application. For more examples of client-side code, refer to the ATG Web Services and Integration Framework Guide.
For more information on using Axis tools to build client applications, visit http://ws.apache.org/axis/.
The class that builds clients is org.apache.axis.wsdl.WSDL2Java
, which takes a WSDL file as one of its arguments. The Axis client generates classes that you can then use to make a call to the GetProfileId
Web service. For example:
java org.apache.axis.wsdl.WSDL2Java -o c:\my\client\classes
/path/to/getProfileId.wsdl
This command creates a class called com.atg.www.webservices.GetProfileIdSEIServiceLocator
. This class is responsible for locating and returning a handle to the service you want to invoke. It returns an item of type com.atg.www.GetProfileIdSEI
, which is an interface that contains the single method you need. You can then call this method with the arguments that are appropriate.
The following example shows how you could use the generated classes as a standalone method within a client application:
import com.atg.www.webservices.*; public callGetProfileId(String pProfileId) { // This finds our Web service GetProfileIdServiceLocator locator = new GetProfileIdServiceLocator(); try { // This represents the Web service that we want to act on GetProfileIdSEI getProfileService = locator.getGetProfileIdSEIPort(); // Now we can invoke our method on it...we know the method name // and args by either looking at the WSDL, or at the // Axis-generated code return getProfileService.getProfileId(pProfileId); } catch(javax.xml.rpc.ServiceException exc) {} catch(java.rmi.RemoteException exc) {} catch(com.atg.www.javax_servlet.ServletException exc) {} catch(com.atg.www.atg_security.SecurityException exc) {} }
Note that the last two exceptions shown are generated by Axis, but you can just catch regular exceptions if the type of exception being thrown is not important to your application.
The Web services provided with the Personalization layer return repository items as Repo2Xml
items. You can manipulate the returned item by means of mapping files that allow you to do the following:
Block certain properties from being returned.
Change the property names in the resulting
Repo2Xml
item.
For example, assume you are returning a user
item, but you do not want the client calling the method to see the value of the scenarioInstances
property. You could set up a mapping file for the user
item descriptor that omits the scenarioInstances
property when Repo2Xml
items are created The syntax for these mapping files is defined in the ATG Web Services and Integration Framework Guide.
Each Web service method that returns Repo2Xml
items has an additional method with an optional String argument for a mapping file name. For example, the getProfile()
method has two signatures: getProfile(String pProfileId)
, and getProfile(String pProfileId, String pMappingFile)
. However, only the former is generated by default. If you want to use the second String and apply a mapping file, you must configure an ItemDescriptorMapping
as described in the ATG Web Services and Integration Framework Guide. In addition, ensure that the useDefaultMappings
property is set to true for the component that the Web service calls.
The atg.security.StandardSecurityPolicy
class, which is provided as part of the Dynamo Application Framework layer, supplies the core logic for controlling access to objects secured using access control lists (ACLs). For more information on the StandardSecurityPolicy
, see the Managing Access Control chapter of the ATG Platform Programming Guide. The security policies used for profile-related Web services, which are described in this section, extend the StandardSecurityPolicy
, appending the ACL returned by the StandardSecurityPolicy
with additional access control entries (ACEs) that either grant or deny access to specific personae. (Personae can be users, roles or organizations.)
For more information on how security policies work with Web services, refer to Web Service Security in the ATG Web Services and Integration Framework Guide and Repository Web Service Security in the ATG Repository Guide.
This section contains the following topics:
This class is abstract and provides the basis for appending entries to the StandardSecurityPolicy
ACL. It extends the getEffectiveAccessControlList
method of the StandardSecurityPolicy
class to append entries to the ACL returned by the StandardSecurityPolicy
instance.
The abstract methods for this class are detailed here.
getAdditionalACL
This abstract method returns the ACL that is appended to the StandardSecurityPolicy
ACL. The getAdditionalACL
method is an extension of the getEffectiveAccessControlList
method that appends the ACL of the StandardSecurityPolicy
instance with additional ACEs. The abstract getAdditionalACL
method returns the ACL to which this is appended. If the StandardSecurityPolicy
does not return an ACL, the return value of getAdditionalACL
is used. If both are null, null is returned and access is granted, which is the default behavior of the StandardSecurityPolicy
.
protected abstract AccessControlList getAdditionalACL(Object pSecuredObject) ;
Return Value
This abstract method returns the ACL that is appended to the StandardSecurityPolicy
ACL.
This is an abstract class that extends the AppendAclPolicy
class. It provides the base implementation for policies that depend on incoming parameter values to determine access rights to the secured object. In the case of Web services, the secured object is always the Web service method. It provides a concrete implementation of getAdditionalACL
that appends all the Personae
returned by the abstract getPersonae
method.
The abstract getPersonae
method takes a map of parameter values created by the getMethodParametersFromSecuredObject
method and the incoming SecuredObject
instance. You can use the incoming parameter values, and the SecuredObject
if necessary, to determine the Personae
that should have access to the SecuredObject
.
For example, a Web service might provide the ability to edit a profile. If you want to allow both the profile owner and users with the Admin
role to make edits, the getPersonae
method could return both Personae
, resulting in an ACL that looks something like the following:
Profile$user$1234:execute;Profile$role$Admin:execute
The access rights for each persona
appended to the ACL are defined in the static variable NEW_PERSONA_RIGHTS
.
Important: If no Personae
are returned from the getPersonae
method, the ACL is appended with deny
access for everyone.
Refer to the ATG Platform API Reference for information on the abstract methods for this class.
The /atg/userprofiling/security/ProfileOwnerPolicy
component (class atg.userprofiling.security.ProfileOwnerPolicy
) is a security policy designed for situations in which you want only the owner of a profile to be able to perform operations on that profile. The ProfileOwnerPolicy
examines the supplied profile object to check that it matches the profile associated with the current session; it then appends the ACL with the owner of the profile.
This policy takes a method argument containing a profile object of type String
or RepositoryItem
.
By default, the ProfileOwnerPolicy
looks for profile objects named pProfileId
, Profile
, profileId
, and profile
, in that order, and uses the first corresponding object that it finds. You can change these names by editing the value of the profileParameterNames
property in the ProfileOwnerPolicy
component.
The /atg/userprofiling/security/ProfileAsXMLOwnerPolicy
component (class atg.userprofiling.security.ProfileAsXMLOwnerPolicy
) is a security policy that is provided with the Personalization layer. It is similar to the ProfileOwnerPolicy
, but it expects a method argument that contains a profile in Repo2Xml
form. It examines this Repo2Xml
item to check that the profile associated with the current session matches the profile in the method argument.
The behavior provided by this policy can be useful for the UpdateUser
service, where you may want to ensure that only the owner of a given profile is allowed to update it. For example, if a user whose ID is 700 attempts to call the updateUser
method with a Repo2Xml
item that represents a profile with ID 900, the ProfileAsXMLOwnerPolicy
prevents the method from being called. Specifically, the ProfileAsXMLOwnerPolicy
looks for method arguments named pProfileAsXML
and ProfileAsXML
in that order. If either of those arguments is present, it uses the value for that argument to determine if the method caller has permission to execute the method.
By default, the ProfileAsXMLOwnerPolicy
looks for profile objects named pProfileAsXML
, ProfileAsXML
, and profileAsXML
, in that order, and uses the first corresponding object that it finds. You can change these names by editing the value of the profileParameterNames
property in the ProfileAsXMLOwnerPolicy
component.
The /atg/userprofiling/security/RelativeRoleByProfileOrgPolicy
component (class atg.userprofiling.security.RelativeRoleByProfileOrgPolicy
) is a security policy implementation that extends the abstract class atg.userprofiling.security.RelativeRoleByOrganizationPolicy
(see ATG Platform API Reference for more information). It allows you to grant access to users with specific relative roles (also called organizational roles – for more information, see Working with the Dynamo User Directory). The roles allowed access are those assigned to the parent organization of the profile supplied in the input argument.
This policy takes a method argument containing a profile object of type String
or RepositoryItem
.
By default, the RelativeRoleByProfileOrgPolicy
looks for profile objects named pProfileId
, Profile
, profileId
, and profile
, in that order, and uses the first corresponding object that it finds. You can change these names by editing the value of the profileParameterNames
property in the RelativeRoleByProfileOrgPolicy
component.
Assume you have a Web service that you want to be used exclusively by supervisors. You create a security policy for it called SupervisorsOnly
that is an implementation of RelativeRoleByProfileOrgPolicy
.
You configure the SupervisorsOnly
component with a roleFunctionName
property set to a single value:
roleFunctionNames=supervisor
When a user calls the Web service, the security policy creates an ACL that grants access to the supervisor role in the user’s parent organization:
$Profile:role:supervisorRoleId
The security sub-system grants access if the calling user has an assigned relative role with the ID supervisorRoleId
; otherwise access is denied.
Each default Web service includes a functionalName
setting. You can use this setting to apply a single security policy across many services at once; for example, you could apply the ProfileOwnerPolicy
to all Web services whose security function setting is profileOwnerOperation
. You can define these functional names and security policy relationships in the Web services administration interface.
ATG does not provide any security policy associations for the default Web services. You must determine which security policy you want to associate with each functional name, and then use the Web services administration interface to set up the relationship. Some suggestions for appropriate policies are provided in the description of each Web service in this chapter. For more information on security policies, refer to Creating and Editing Security Configurations in the ATG Web Services and Integration Framework Guide.
After you set up security policy associations, or if you change any of the default functional names, you must regenerate and then redeploy the affected Web services. For more information on this procedure, see the ATG Web Services and Integration Framework Guide.
The following list shows the functionalName
setting for each Web service:
Web Service | Functional Name |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Standard practice for most applications that transmit passwords is to use a secure protocol such as HTTPS, which handles password encryption internally. The LoginUser
Web service, however, includes an option that permits a client-side application to encrypt passwords and then log in a user without using a secure protocol. Important: ATG strongly recommends using a secure protocol for all operations that transmit confidential information, including logins. The client-side password encryption feature built into the LoginUser
service exists as an option for customers with unusual login requirements, and it is not recommended for general use.
To use this feature, client applications must follow very specific ATG-defined rules for encrypting cleartext passwords. If a password is encrypted in a way the ATG server does not understand, the login authentication will fail. Note also that the rules for encryption vary according to the password hasher your application uses; for example, the MD5PasswordHasher
hashes passwords in a different way from the SaltedDigestPasswordHasher
.
Not all password hashers permit the client-side encryption of passwords. Applications whose password hashers do not provide a temporary encryption key to be used for logins cannot use client-side encryption. This temporary encryption key is needed so that the client does not send a password string that is identical to the stored password in the database. The CanClientEncryptPasswords Web Service determines if the current application allows client-side encryption. Currently, only the MD5PasswordHasher has well-defined rules for client-side encryption, and it is the only password hasher supported for this feature.
The process of passing an encrypted password from a client application to the LoginUser
Web service is called a password encryption conversation. A restriction of this feature is that the entire password encryption conversation must be completed within a certain time limit, defined by the maxAuthenticationWait
property of the ProfileServices
component. This time limit starts the moment a client calls GetPasswordHashKey
and ends the moment that same client calls LoginUser
.
The following procedure describes how to have your application use the client-side password encryption feature to log in a user. Note that the procedure assumes your application uses the MD5PasswordHasher
.
Call the
CanClientEncryptPasswords
Web service.If
CanClientEncryptPasswords
returns false, use HTTPS and send the password as cleartext. Call theLoginUser
service using the following parameters:loginUser(login, cleartext_password, false)
.If
CanClientEncryptPasswords
returns true, call thegetPasswordHashAlgorithm
service.Use the returned algorithm to encrypt the user’s password.
Call the
GetPasswordHashKey
service. Note that the conversation timer is started here. The client application hasmaxAuthenticationWait
milliseconds to call theLoginUser
service. IfLoginUser
is not called quickly enough, an error is thrown when the service is eventually called.Encrypt a combination of the returned
hashKey
and the encrypted password from step 4, again using the algorithm returned from step 3.Call the
LoginUser
service using the following parameters:loginUser(login, encrypted_password_from_step_6, true)
.