Subscriber Integration

C H A P T E R 3

Sun Java System Content Delivery Server uses an Oracle database to manage subscriber profiles. If you already have extensive subscriber data, you do not need to duplicate this information. Content Delivery Server can be configured to work with your existing subscriber data.

A subscriber adapter maps external subscriber data to the data required by Content Delivery Server when processing subscriber-related functions.

This chapter describes the subscriber adapter provided with Content Delivery Server. You can create your own subscriber adapter using the User Profile API. See the Sun Java System Content Delivery Server Customization Guide for information on this API.

This chapter includes the following topics:

Subscriber Adapter Provided

Using a Subscriber Adapter

Working With LDAP

Subscriber Account Management

Automatic Provisioning of Subscribers

3.1 Subscriber Adapter Provided

Currently, the subscriber adapter provided with Content Delivery Server supports the Lightweight Directory Access Protocol (LDAP) format. The LDAP subscriber adapter uses an XML file to map data between Content Delivery Server and your LDAP directory.

3.2 Using a Subscriber Adapter

To specify the subscriber adapter that you want to use, you must set the module.security.subscriber.usermanager property to the fully qualified class name of the subscriber adapter. This property is in the security.conf file found in the $CDS_HOME/deployment/deployment-name/conf directory. Use one of the values shown in the following table.

Adapter	Value for the `module.security.subscriber.usermanager` Property
Oracle	`com.sun.content.server.vending.security.user.SubscriberImpl` Use this value to use Content Delivery Server database to store all subscriber data. This is the default setting.
LDAP	`com.sun.content.server.vending.security.user.ldap.ldapusermanager.LDAPUserManager` Use this value to use an external LDAP directory for subscriber data.

Adapter

Value for the module.security.subscriber.usermanager Property

Oracle

com.sun.content.server.vending.security.user.SubscriberImpl

Use this value to use Content Delivery Server database to store all subscriber data. This is the default setting.

LDAP

com.sun.content.server.vending.security.user.ldap.ldapusermanager.LDAPUserManager

Use this value to use an external LDAP directory for subscriber data.

To use the subscriber adapter for LDAP, you must also provide an XML file that describes the mapping to be used. This file is described in Section 3.3.1, Creating the Mapping File for LDAP.

3.3 Working With LDAP

This section provides additional information on setting up your system to work with Content Delivery Server when your subscriber data is stored in an LDAP directory. Section 3.3.1, Creating the Mapping File for LDAP describes how to create a file that maps the fields in the LDAP directory to the fields in Content Delivery Server. Section 3.3.2, Configuring Access for Sun Java System Application Server describes changes that are needed to the security policy if you are using Sun Java System Application Server. Section 3.3.3, Tuning LDAP describes how to set up LDAP to improve performance.

3.3.1 Creating the Mapping File for LDAP

To use subscriber data in an LDAP directory, you must create a mapping file in XML that maps the data needed by Content Delivery Server to the information in the LDAP directory. The conf.xml file in the $CDS_HOME/deployment/deployment-name/conf directory contains a sample mapping.

To create a mapping file:

1. Copy the conf.xml file to a new file in the same directory, for example, cdsmapping.xml.

2. Edit your file to define the mapping of your LDAP data.

Section 3.3.1.1, Subscriber Data for Content Delivery Server identifies the data that must be provided to Content Delivery Server. Section 3.3.1.2, Sample Mapping File provides a sample file.

3. Direct Content Delivery Server to use your file.

Set the cds.security.ldapusermanager.config_file property in the $CDS_HOME/deployment/deployment-name/conf/security.config file to the name of your file.

3.3.1.1 Subscriber Data for Content Delivery Server

The first few lines of the mapping file contain the connection information for the LDAP server. The following tables describe the properties in the mapping file.

TABLE 3-1 describes the configuration properties that must be set.

TABLE 3-1 Configuration Properties
Property	Description
`search_scope`	Scope of the search. Specify one of the following values: `0` - Searches the named object. `1` - Searches only one level of the named object. This is the default. `2` - Searches the entire sub-tree of the named object.
`max_search_wait_time`	Maximum time in milliseconds that LDAP executes a search request. Use a negative value to indicate no limit.

TABLE 3-2 describes the properties that define your LDAP environment.

TABLE 3-2 LDAP Properties
Property	Description
`initial_context_factory`	Fully qualified class name of the initial context factory.
`provider_url`	URL of the provider (LDAP server). Note - If you are using Sun Java System Application Server, the URL must not contain spaces.
`prefix`	Prefix used.
`username`	User-distinguished name used to access LDAP.
`password`	Password associated with the user name.
`master_username`	User name for the master server. This property is optional.
`master_password`	Password associated with the master user name. This property is optional.
`object`	One or more objects from LDAP.

TABLE 3-3 identifies the subscriber data used by Content Delivery Server. Add an element with the field name in the XML file that you create. The required fields are noted.

TABLE 3-3 Subscriber Data
Content Delivery Server Field	Description
`loginId`	Login ID used by the subscriber to access the Subscriber Portal. Note - This field is required and must be mapped.
`password`	Password for the login ID provided. Note - This field is required and must be mapped.
`uniqueDeviceId`	Unique ID that identifies the subscriber by the device being used. Typically, this is the same as the MSISDN. Note - This field is required and must be mapped.
`firstName`	First name of the subscriber. Note - This field is required and must be mapped.
`middleName`	Middle initial of the subscriber.
`lastName`	Last name of the subscriber. Note - This field is required and must be mapped.
`gender`	Gender of the subscriber.
`street1`	Street address for the subscriber.
`street2`	Any additional address information required for the subscriber.
`city`	City information for the subscriber.
`state`	State information for the subscriber.
`postalcode`	Postal code for the subscriber.
`country`	Country where the subscriber resides.
`email`	Email address for the subscriber, used when sending password reminders or campaign notifications. Note - This field is required and must be mapped.
`phone`	Phone number for the subscriber.
`activatedate`	Date on which the subscriber account was activated.
`deactivatedate`	Date on which the subscriber account was deactivated.
`salutation`	Salutation by which the subscriber prefers to be addressed.
`enabled`	Status of the subscriber. If no value is provided, the default is enabled.
`msisdn`	TMSISDN number for the subscriber, used when sending messages to the subscriber’s device. Note - This field is required and must be mapped.

The mapping is contained in the <mapping>...</mapping> section of the XML file. The mapping element has the following attributes:

isDeletable. Set to true to allow user records to be deleted by Content Delivery Server. Set to false to prevent user records from being deleted.

isAddable. Set to true to allow user records to be created by Content Delivery Server. Set to false to prevent user records from being created.

Each element in the mapping section can have one or more of the following attributes:

isRequired. Set to true to indicate that the mapped field must not be null or empty. Set to false to indicate that the mapped field can be null or empty. If this attribute is set to true and a null or empty value is returned from the LDAP directory, an error message is generated.

isModifiable. Set to true to allow the field to be modified by Content Delivery Server. Set to false to prevent the field from being modified.

isMultiple. Set to true to indicate that more than one field in LDAP maps to the field in Content Delivery Server. If this attribute is true, you must include a valuen element for each LDAP field, where n is a sequential number from 0 to number of fields - 1. For example, if the uniqueDeviceId field maps to handsetID and mobileID, you would add the following statements:

<uniqueDeviceID isMultiple=”true”>
   <value0>handsetID</value0>
   <value1>mobileID</value1>
</uniqueDeviceID>

The password element can also have the attribute isEncoded. Set this attribute to true if the password is stored as an encoded string. Set to false if the password is stored without encoding. The default is false.

See Section 3.3.1.2, Sample Mapping File for an example.

3.3.1.2 Sample Mapping File

TABLE 3-4 describes sample data that is mapped in the sample mapping file that follows. Fields identified as having no mapping do not appear in the sample.

TABLE 3-4 Data for Sample LDAP File
Content Delivery Server Field	LDAP Field
`loginId`	`SSN`
`password`	`pwd`
`uniqueDeviceId`	`handsetID`, `mobileID`
`firstName`	`givenName`
`middleName`	(no mapping)
`lastName`	`familyName`
`gender`	(no mapping)
`street1`	`street`
`street2`	(no mapping)
`city`	`city`
`state`	(no mapping)
`postalcode`	`zipcode`
`country`	(no mapping)
`email`	`email`
`phone`	(no mapping)
`activatedate`	(no mapping)
`deactivatedate`	(no mapping)
`salutation`	(no mapping)
`enabled`	`status`
`msisdn`	`msisdn`

CODE EXAMPLE 3-1 Sample Mapping File for LDAP Data
<ldapusermanager> <config> <search_scope>1</search_scope> <max_search_wait_time>1000</max_search_wait_time> </config> <ldap> <initial_context_factory>com.sun.jndi.ldap.LdapCtxFactory </initial_context_factory> <provider_url>ldap://t1:389/ou=Users,o=LDAPUserManager </provider_url> <prefix>uid=</prefix> <username>cn=directory manager</username> <password>ldappwd</password> <master_username>cn=directory manager</master_username> <master_password>ldappwd</master_password> </ldap> <object> <obj0>top</obj0> <obj1>person</obj1> <obj2>organizationalPerson</obj1> </object> <mapping isDeletable=”true” isAddable=”true”> <loginId isRequired=”true”>SSN</loginId> <password isRequired=”true” isEncoded=”false”>pwd</password> <uniqueDeviceId isRequired=”true” isModifiable=”true” isMultiple=”true”> <value0>handsetID</value0> <value1>mobileID</value1> </uniqueDeviceId> <firstName isRequired=”true”>givenName</firstName> <lastName isRequired=”true”>familyName</lastName> <street1>street</street1> <city>city</city> <postalcode>zipcode<postalcode> <email isRequired=”true”>email</email> <enabled isRequired=”true”>status</enabled> <msisdn isRequired=”true” isModifiable=”true”>msisdn</msisdn> </mapping> </ldapusermanager>

CODE EXAMPLE 3-1 Sample Mapping File for LDAP Data

<ldapusermanager>
  <config>
    <search_scope>1</search_scope>
    <max_search_wait_time>1000</max_search_wait_time>
  </config>
  <ldap>
    <initial_context_factory>com.sun.jndi.ldap.LdapCtxFactory
    </initial_context_factory>
    <provider_url>ldap://t1:389/ou=Users,o=LDAPUserManager
    </provider_url>
    <prefix>uid=</prefix>
    <username>cn=directory manager</username>
    <password>ldappwd</password>
    <master_username>cn=directory manager</master_username>
    <master_password>ldappwd</master_password>
  </ldap>
  <object>
    <obj0>top</obj0>
    <obj1>person</obj1>
    <obj2>organizationalPerson</obj1>
  </object>
  <mapping isDeletable=”true” isAddable=”true”>
    <loginId isRequired=”true”>SSN</loginId>
    <password isRequired=”true” isEncoded=”false”>pwd</password>
    <uniqueDeviceId isRequired=”true” isModifiable=”true” isMultiple=”true”>
      <value0>handsetID</value0>
      <value1>mobileID</value1>
    </uniqueDeviceId>
    <firstName isRequired=”true”>givenName</firstName>
    <lastName isRequired=”true”>familyName</lastName>
    <street1>street</street1>
    <city>city</city>
    <postalcode>zipcode<postalcode>
    <email isRequired=”true”>email</email>
    <enabled isRequired=”true”>status</enabled>
    <msisdn isRequired=”true” isModifiable=”true”>msisdn</msisdn>
  </mapping>
</ldapusermanager>

3.3.2 Configuring Access for Sun Java System Application Server

If you are using Sun Java System Application Server, you must modify the security policy to grant access permission to classes used by the LDAP subscriber adapter. Edit the server.policy file located in the $CDS_HOME/deployment/deployment-name/sun/domains/server-domain/config directory and add the following statements:

grant {
    permission java.security.SecurityPermission "insertProvider.SunJSSE";
    permission java.lang.RuntimePermission "setFactory";
    permission java.net.NetPermission "specifyStreamHandler";
};

Restart Content Delivery Server after you save your changes.

3.3.3 Tuning LDAP

When using an LDAP directory as the subscriber database, you might want to create an index on any attribute mapped to the unique device ID, login ID, or MSISDN to improve performance. See the documentation for the LDAP directory that you are using for instructions on creating an index. Create the index on the attribute that is mapped to uniqueDeviceId in the mapping file that you created.

Creating an index is resource intensive and could affect system performance. Choose a time to create the index that is least likely to impact users.

3.4 Subscriber Account Management

A subscriber account contains information that identifies the subscriber and the device used to access Content Delivery Server. Subscriber accounts are managed by the Vending Manager administrator through the Vending Manager administration console. Subscribers can also access their own accounts through the Subscriber Portal.

You can configure the options presented to the subscriber and the administrator. For example, you can allow subscribers to only view their accounts, or prevent administrators from deleting accounts. You can also configure which fields subscribers or administrators can edit. For example, you can prevent subscribers from changing their mobile phone numbers, or prevent administrators from changing the subscribers’ names.

To specify the options that you want to make available and the fields that can be edited, edit the following files found in the $CDS_HOME/deployment/deployment-name/conf directory:

subsubmgr.xml. Configure this file to specify the actions that the subscriber can take through the Subscriber Portal.

vsadminsubmgr.xml. Configure this file to specify the actions that the administrator can take through the Vending Manager administration console.

The actions for managing subscriber accounts are add, edit, and delete. These actions are represented by the <add>, <edit>, and <delete> elements in the files. To allow an action, set the isEnabled attribute to true. To prevent an action, set the isEnabled attribute to false. The default is false. For example, to prevent subscribers from creating an account, include the following statement in the subsubmgr.xml file:

<add isEnabled=”false”/>

The elements within the <edit> element in each of the files show the fields that you can manage. Fields that are not represented by an element in the file, such as the login ID, are managed only by Content Delivery Server. Valid attributes for these fields are isReadOnly and isRequired. To prevent a field from being changed, set the isReadOnly attribute to true. To enable the field to be changed, set the isReadOnly parameter to false. The default is false.

Note - The isRequired attribute must be set to true for the password, mobile_id, first_name, last_name, email, and status elements.

The following code shows the relevant section of the default subsubmgr.xml file.

CODE EXAMPLE 3-2 Sample `subsubmgr.xml` File
<subscriber> <subscriber> <!-- For adding --> <add isEnabled="true"/> <!-- For editing --> <edit isEnabled="true"> <password isRequired="true"/> <mobile_id isRequired="true" isReadOnly="true"/> <first_name isRequired="true"/> <middle_name/> <last_name isRequired="true"/> <salutation/> <gender/> <street_1/> <street_2/> <city/> <state/> <postal_code/> <country_code/> <email isRequired="true"/> <contact_phone/> </edit> </subscriber> </subscriber>

CODE EXAMPLE 3-2 Sample subsubmgr.xml File

<subscriber>
   <subscriber>
      <!-- For adding -->
      <add isEnabled="true"/>
      <!-- For editing -->
      <edit isEnabled="true">
         <password isRequired="true"/>
         <mobile_id isRequired="true" isReadOnly="true"/>
 
         <first_name isRequired="true"/>
         <middle_name/>
         <last_name isRequired="true"/>
         <salutation/>
         <gender/>
 
         <street_1/>
         <street_2/>
         <city/>
         <state/>
         <postal_code/>
         <country_code/>
 
         <email isRequired="true"/>
         <contact_phone/>
      </edit>
   </subscriber>
</subscriber>

The following code shows the relevant section of the default vsadminsubmgr.xml file.

CODE EXAMPLE 3-3 Sample `vsadminsubmgr.xml` File
<vsadmin> <subscriber> <!-- For adding --> <add isEnabled="true"/> <!-- For editing --> <edit isEnabled="true"> <password isRequired="true"/> <status isRequired="true"/> <mobile_id isRequired="true"/> <first_name isRequired="true"/> <middle_name/> <last_name isRequired="true"/> <salutation/> <gender/> <street_1/> <street_2/> <city/> <state/> <postal_code/> <country_code/> <email isRequired="true"/> <contact_phone/> </edit> <!-- For deleting --> <delete isEnabled="true"/> </subscriber> </vsadmin>

CODE EXAMPLE 3-3 Sample vsadminsubmgr.xml File

<vsadmin>
   <subscriber>
      <!-- For adding -->
      <add isEnabled="true"/>
      <!-- For editing -->
      <edit isEnabled="true">
         <password isRequired="true"/>
         <status isRequired="true"/>
         <mobile_id isRequired="true"/>
 
         <first_name isRequired="true"/>
         <middle_name/>
         <last_name isRequired="true"/>
         <salutation/>
         <gender/>
 
         <street_1/>
         <street_2/>
         <city/>
         <state/>
         <postal_code/>
         <country_code/>
 
         <email isRequired="true"/>
         <contact_phone/>
      </edit>
      <!-- For deleting -->
      <delete isEnabled="true"/>
   </subscriber>
</vsadmin>

3.5 Automatic Provisioning of Subscribers

To provision a subscriber is to register that subscriber and create an entry in the subscriber database. You can configure Content Delivery Server to automatically provision unregistered subscribers when they access the Subscriber Portal. If auto-provisioning is enabled and an unregistered subscriber attempts to download content, a subscriber account is created using the MSISDN number and the download is allowed.

The following properties are available in the $CDS_HOME/deployment/deployment-name/conf/SubscriberPortal.properties file for setting up auto-provisioning:

auto_provision.unknown.user - Determines if unknown subscribers are automatically registered with Content Delivery Server. Set this property to true to automatically register unknown subscribers when they access Content Delivery Server. Set to false to prevent unknown subscribers from being registered automatically. The default is false.

auto_provision.unknown.userpeer - Determines if subscribers can access Content Delivery Server without registering. Set this property to true to enable subscribers to access the system without registering with Content Delivery Server. Set to false to force subscribers to register before accessing the system. If set to true and auto_provision.unknown.user is also set to true, a subscriber account is automatically created for the unknown subscriber. The default is true.

auto_provision.unknown.userpeer.gifting - Determines if unknown recipients of gifts or sharing are automatically registered. Set this property to true for Content Delivery Server to attempt to automatically create a subscriber account for an unknown subscriber to whom content has been gifted or shared. Set to false to prevent the automatic provisioning of the unknown recipient. The default is true.

auto_provision.unknown.userpeer.mobile_originated - Determines if a new subscriber account is provisioned when a Mobile Originated (MO) request for content is received from an unregistered user. Set this property to true to provision an account when an MO request is received. Set to false to prevent the account from being provisioned. The default is true.

auto_provision.unknown.user.firstName - Provides the value used for the subscriber’s first name when provisioning an unknown user. The default is External User.

auto_provision.unknown.user.lastName - Provides the value used for the subscriber’s last name when provisioning an unknown user. The default is External User.

auto_provision.unknown.user.middleName - Provides the value used for the subscriber’s middle name when provisioning an unknown user. The default is External User.

auto_provision.unknown.user.enabled - Specifies if the account created for an unknown user is enabled. Set the property to true to enable the account. Set to false to disable the account. The default is true.

auto_provision.unknown.user.email - Provides the value used for the subscriber’s email address when provisioning an unknown user. The default is @external.com.