Part III. Web Services for Personalization and Scenarios

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:

User Profiling Web Services

Content Targeting Web Services

Messaging Web Services

Example: Using the GetProfileId Web Service in an Axis Client

Returning RepositoryItems as Repo2Xml Items

Profile-Related Security Policies for Web Services

Using Client-Side Password Encryption

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:

ProfileServices Component

GetProfileId Web Service

GetProfile Web Service

LoginUser Web Service

LogoutUser Web Service

CreateUser Web Service

UpdateUser Web Service

Set Password Web Service

SetContactInfo Web Service

SetLocale Web Service

CanClientEncryptPasswords Web Service

GetPassWordHashKey Web Service

GetPasswordHashAlgorithm Web Service

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.

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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

getProfileId

Web Service URL

http://hostname:port/userprofiling/usersession/getProfileId

WSDL URL

http://hostname:port/userprofiling/usersession/getProfileId?WSDL

Web Service Class

webservice.GetProfileIdSEIImpl

Input Parameters

String Login

Output

String ProfileId

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

getProfileId(String pLogin)

Executes within a session

Yes

Security FunctionalName

profileInfoOperation

getProfileId Method

The GetProfileId Web service calls the getProfileId method in the underlying atg.userprofiling.ProfileServices implementation.

The getProfileId method does the following:

  1. Calls ProfileTools.getItem() with the given login.

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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

getProfile

Web Service URL

http://hostname:port/userprofiling/usersession/getProfile

WSDL URL

http://hostname:port/userprofiling/usersession/getProfile?WSDL

Web Service Class

webservice.GetProfileSEIImpl

Input Parameters

String ProfileId

Output

String ProfileAsXML

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

getProfile(String pProfileId)

Executes within a session

Yes

Security FunctionalName

profileInfoOperation

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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

loginUser

Web Service URL

http://hostname:port/userprofiling/usersession/loginUser

WSDL URL

http://hostname:port/userprofiling/usersession/loginUser?WSDL

Web Service Class

webservice.LoginUserSEIImpl

Input Parameters

String Login
String Password
boolean IsPasswordEncrypted

Output

String ProfileId

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

loginUser(String pLogin, String pPassword, boolean pIsPasswordEncrypted)

Executes within a session

Yes

Security FunctionalName

loginOperation.

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:

  1. If pIsPasswordEncrypted is true, the loginUser method checks to see if a valid password encryption conversation has occurred in this session. If not, a ServletException is thrown.

  2. loginUser calls the preLoginUser 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 login securityStatus (if securityStatus 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.

  3. loginUser calls doLoginUser, which attempts to authenticate the user based on the given credentials. It forward-hashes the stored password for the given user with a hashKey initialized during the password encryption conversation and compares it to the password argument. If this check succeeds, the RepositoryItem 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.

  4. The profile ID is returned for the user who just logged in.

  5. If the password encryption comparison fails, indicating that either the login name or the password was invalid, null is returned by doLoginUser.

  6. The loginUser method calls the postLoginUser method, which sends a login event if configured to do so (set generateLoginEvents to true in the ProfileServices 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

logoutUser

Web Service URL

http://hostname:port/userprofiling/usersession/logoutUser

WSDL URL

http://hostname:port/userprofiling/usersession/logoutUser?WSDL

Web Service Class

webservice.LogoutUserSEIImpl

Input Parameters

None

Output

None

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

logoutUser()

Executes within a session

Yes

Security FunctionalName

logoutOperation.

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:

  1. Calls preLogoutUser, which sets up a logout event and revokes the current user’s identity.

  2. Calls doLogoutUser.

  3. Calls postLogoutUser, which fires a logout event and expires the current session if configured to do so. (You can control this behavior through the generateLogoutEvents and expireSessionOnLogout properties in the ProfileServices 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

createUser

Web Service URL

http://hostname:port/userprofiling/usersession/createUser

WSDL URL

http://hostname:port/userprofiling/usersession/createUser?WSDL

Web Service Class

webservice.CreateUserSEIImpl

Input Parameters

String ProfileAsXML

Output

String ProfileId

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

createUser(String pProfileAsXml)

Executes within a session

Yes

Security FunctionalName

createOperation

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:

  1. Calls preCreateUser.

  2. Calls doCreateUser, which uses a Repo2XmlAddService 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 the pProfileAsXML are cleartext.)

  3. Calls postCreateUser, which sets profile cookies if required to do so. postCreateUser also fires a register event if you set the generateRegisterEvents to true in the ProfileServices 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

updateUser

Web Service URL

http://hostname:port/userprofiling/usersession/updateUser

WSDL URL

http://hostname:port/userprofiling/usersession/updateUser?WSDL

Web Service Class

webservice.UpdateUserSEIImpl

Input Parameters

String ProfileAsXML

Output

None

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

updateUser(String pProfileAsXml)

Executes within a session

Yes

Security FunctionalName

xmlProfileOwnerOperation

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:

  1. Calls preUpdateUser, which sets up a ProfileUpdateEvent but does not fire it.

  2. Calls doUpdateUser, which uses a Repo2Xml update service to update the given pProfileAsXML.

  3. Calls postUpdateUser, which may revoke profile cookies if the user’s autoLogin property changes from true to false. It also fires a ProfileUpdateEvent if configured to do so (set generateUpdateEvents to true in the ProfileServices 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

setPassword

Web Service URL

http://hostname:port/userprofiling/usersession/setPassword

WSDL URL

http://hostname:port/userprofiling/usersession/setPassword?WSDL

Web Service Class

webservice.SetPasswordSEIImpl

Input Parameters

String ProfileId
String OriginalPassword
String NewPassword

Output

None

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

setPassword(String pProfileId, String pOriginalPassword, String pNewPassword)

Executes within a session

Yes

Security FunctionalName

profileOwnerOperation

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:

  1. Calls preSetPassword.

  2. Calls doSetPassword, which compares the password currently stored for the user (specified by the supplied profile ID) with the given pOldPassword. If the check succeeds, the user’s password is set to pNewPassword.

  3. 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

setContactInfo

Web Service URL

http://hostname:port/userprofiling/usersession/setContactInfo

WSDL URL

http://hostname:port/userprofiling/usersession/setContactInfo?WSDL

Web Service Class

webservice.SetContactInfoSEIImpl

Input Parameters

String ProfileId
String ContactInfoAsXML

Output

None

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

setContactInfo(String pProfileId, String pContactInfoAsXml)

Executes within a session

Yes

Security FunctionalName

profileOwnerOperation

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:

  1. Checks that the given pProfileId resolves to a valid profile.

  2. Takes the pContactInfoAsXML and uses it to get or create a RepositoryItem.

  3. Sets the contact information property of the user represented by pProfileId to the RepositoryItem 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

setLocale

Web Service URL

http://hostname:port/userprofiling/usersession/setLocale

WSDL URL

http://hostname:port/userprofiling/usersession/setLocale?WSDL

Web Service Class

webservice.SetLocaleSEIImpl

Input Parameters

String ProfileId
String LocaleName

Output

None

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

setLocale(String pProfileId, String pLocaleName)

Executes within a session

Yes

Security FunctionalName

profileOwnerOperation

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:

  1. Checks that the given pProfileId resolves to a valid profile.

  2. If the locale property exists, sets the locale property of the given user to pLocaleName.

  3. 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

canClientEncryptPasswords

Web Service URL

http://hostname:port/userprofiling/usersession/
canClientEncryptPasswords

WSDL URL

http://hostname:port/userprofiling/usersession/
canClientEncryptPasswords?WSDL

Web Service Class

webservice.CanClientEncryptPasswordsSEIImpl

Input Parameters

None

Output

boolean CanEncryptPasswords

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

canClientEncryptPasswords()

Executes within a session

Yes

Security FunctionalName

loginOperation

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:

  1. The allowEncryptedPasswords property of ProfileServices is set to true.

  2. The password hasher configured for the application supports temporary encryption keys.

  3. 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

getPasswordHashKey

Web Service URL

http://hostname:port/userprofiling/usersession/
getPasswordHashKey

WSDL URL

http://hostname:port/userprofiling/usersession/
getPasswordHashKey?WSDL

Web Service Class

webservice.GetPasswordHashKeySEIImpl

Input Parameters

None

Output

String PasswordHashKey

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

getPasswordHashKey()

Executes within a session

Yes

Security FunctionalName

loginOperation

getPasswordHashKey Method

The GetPasswordHashKey Web service calls the getPasswordHashKey method in the underlying atg.userprofiling.ProfileServices implementation.

The getPasswordHashKey method acts as follows:

  1. Returns null if not called in the context of a request.

  2. Sets up session attributes to indicate that a password encryption conversation has started.

  3. 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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

getPasswordHashAlgorithm

Web Service URL

http://hostname:port/userprofiling/usersession/
getPasswordHashAlgorithm

WSDL URL

http://hostname:port/userprofiling/usersession/
getPasswordHashAlgorithm?WSDL

Web Service Class

webservice.GetPasswordHashAlgorithmSEIImpl

Input Parameters

None

Output

String PasswordHashAlgorithm

Nucleus Component

/atg/userprofiling/ProfileServices (class atg.userprofiling.ProfileServices)

Method

getPasswordHashAlgorithm()

Executes within a session

Yes

Security FunctionalName

loginOperation

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:

  1. If the PasswordHasher used for this application is not supported, the getPasswordHashAlgorithm method throws a ServletException. (Note that only MD5 is currently supported.)

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

TargetingServices Component

RecommendContent Web Service

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:

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

userprofilingWebServices.ear

WAR file

usersession.war

Context root

userprofiling/usersession

Servlet

recommendContent

Web Service URL

http://hostname:port/userprofiling/usersession/
recommendContent

WSDL URL

http://hostname:port/userprofiling/usersession/
recommendContent?WSDL

Web Service Class

webservice.ExecuteRepositoryTargeterSEIImpl

Input Parameters

String PathToSlotOrTargeter. Represents the Nucleus component path of the targeter or slot to execute.

int StartingIndex. Represents the 0-based index at which to start when returning values. For example, passing in “3” here returns an array of items starting with the fourth item that is returned from the targeting operation (in other words, the first three items are skipped).

int HowMany. Indicates how many items should be returned in total from this targeter. If this value is -1, all items are returned, starting from the StartingIndex value.

Output

String[] ContentAsXML

Nucleus Component

/atg/targeting/TargetingServices (class atg.targeting.TargetingServices)

Method

executeRepositoryTargeter (String pPathToSlotOrTargeter, int pStartingIndex, int pHowMany)

Executes within a session

Yes

Security FunctionalName

targetingOperation

executeRepositoryTargeter Method

The RecommendContent Web service calls the executeRepositoryTargeter method in the underlying atg.targeting.TargetingServices implementation. This method does the following:

  1. Resolves the given pTargeterPath by attempting to use the current request as a NameResolver.

  2. If a slot or targeter is found, the target() method is called. pStartingIndex and pMaxResults are passed in as arguments.

  3. 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:

MessagingImporter Component and ReceiveObjectMessage() Method

ContentViewed Web Service

ContentConsumed Web Service

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 Web services that call this method take a message object as their input parameter.

For more information, refer toJMS Web Services in the ATG Web Services and Integration Framework Guide.

The ContentViewed Web service sends a PageVisitMessage to Patch Bay.

EAR file

userprofilingWebServices.ear

WAR file

messaging.war

Context root

userprofiling/messaging

Servlet

contentViewed

Web Service URL

http://hostname:port/userprofiling/messaging/contentViewed

WSDL URL

http://hostname:port/userprofiling/messaging/contentViewed?WSDL

Web Service Class

webservice.SendPageVisitSEIImpl

Input Parameters

atg.userprofiling.dms.PageVisitMessage pMessage

Output

None

Nucleus Component

/atg/dynamo/messaging/MessagingImporter (class atg.dms.patchbay.MessageImporter)

Method

receiveObjectMessage (Object pMessage, String pJMSType, String pInputPortName)

Note that for the default ContentViewed service:

JMSType = atg.dps.PageVisit
InputPortName = IndividualEvents

Executes within a session

Yes

Security FunctionalName

messagingOperation

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

userprofilingWebServices.ear

WAR file

messaging.war

Context root

userprofiling/messaging

Servlet

contentConsumed

Web Service URL

http://hostname:port/userprofiling/messaging/contentConsumed

WSDL URL

http://hostname:port/userprofiling/messaging/contentConsumes?WSDL

Web Service Class

webservice.SendClickThroughSEIImpl

Input Parameters

atg.userprofiling.dms.ClickThroughMessage pMessage

Output

None

Nucleus Component

/atg/dynamo/messaging/MessagingImporter (class atg.dms.patchbay.MessageImporter)

Method

receiveObjectMessage (Object pMessage, String pJMSType, String pInputPortName)

Note that for the default ContentConsumed service:

JMSType = atg.dps.ClickThrough
InputPortName = IndividualEvents

Executes within a session

Yes

Security FunctionalName

messagingOperation

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:

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

AppendACLPolicy

MethodParameterPolicy

ProfileOwnerPolicy

ProfileAsXMLOwnerPolicy

RelativeRoleByProfileOrgPolicy

Defining Security Functions and Policies

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

GetProfileId

profileInfoOperation

GetProfile

profileInfoOperation

LoginUser

loginOperation

LogoutUser

logoutOperation

UpdateUser

xmlProfileOwnerOperation

CreateUser

createOperation

SetContactInfo

profileOwnerOperation

SetPassword

profileOwnerOperation

SetLocale

profileOwnerOperation

CanClientEncryptPasswords

loginOperation

GetPasswordHashKey

loginOperation

GetPasswordHashAlgorithm

loginOperation

RecommendContent

targetingOperation

ContentViewed

messagingOperation

ContentConsumed

messagingOperation

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.

  1. Call the CanClientEncryptPasswordsWeb service.

  2. If CanClientEncryptPasswords returns false, use HTTPS and send the password as cleartext. Call the LoginUser service using the following parameters: loginUser(login, cleartext_password, false).

  3. If CanClientEncryptPasswords returns true, call the getPasswordHashAlgorithm service.

  4. Use the returned algorithm to encrypt the user’s password.

  5. Call the GetPasswordHashKey service. Note that the conversation timer is started here. The client application has maxAuthenticationWait milliseconds to call the LoginUser service. If LoginUser is not called quickly enough, an error is thrown when the service is eventually called.

  6. Encrypt a combination of the returned hashKey and the encrypted password from step 4, again using the algorithm returned from step 3.

  7. Call the LoginUser service using the following parameters: loginUser(login, encrypted_password_from_step_6, true).

 
loading table of contents...